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.

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

_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.

Get a project

Retrieve the details of a single project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "attributes": {
    },
  • "title": "string",
  • "description": "string",
  • "owner": "string",
  • "namespace": "string",
  • "organization": "string",
  • "default_branch": "string",
  • "status": {
    },
  • "timezone": "string",
  • "region": "string",
  • "repository": {
    },
  • "default_domain": "string",
  • "subscription": {
    }
}

Update a project

Update the details of an existing project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
object (Arbitrary attributes attached to this resource)
title
string (Title)
description
string (Description)
default_branch
string or null (Default branch)
timezone
string (Timezone of the project)
region
string (Region)
default_domain
string or null (Default domain)

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "title": "string",
  • "description": "string",
  • "default_branch": "string",
  • "timezone": "string",
  • "region": "string",
  • "default_domain": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete a project

Delete the entire project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "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.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "custom_domains": {
    },
  • "source_operations": {
    },
  • "runtime_operations": {
    },
  • "outbound_firewall": {
    },
  • "metrics": {
    },
  • "images": {
    },
  • "instance_limit": 0,
  • "integrations": {
    }
}

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:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "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.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
One of
name
required
string (Domain name)
object (Arbitrary attributes attached to this resource)
is_default
boolean (Is this domain default)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "attributes": {
    },
  • "is_default": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a project domain

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
domainId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "project": "string",
  • "name": "string",
  • "registered_name": "string",
  • "attributes": {
    },
  • "is_default": true
}

Update a project domain

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
domainId
required
string
Request Body schema: application/json
One of
object (Arbitrary attributes attached to this resource)
is_default
boolean (Is this domain default)

Responses

Request samples

Content type
application/json
Example
{
  • "attributes": {
    },
  • "is_default": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete a project domain

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
domainId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a list of environment domains

Retrieve a list of objects representing the user-specified domains associated with an environment. Note that this does not return the .platformsh.site subdomains, which are automatically assigned to the environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an environment domain

Add a single domain to an environment. If the environment is not production, the replacement_for field is required, which binds a new domain to an existing one from a production environment. 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.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
One of
name
required
string (Domain name)
object (Arbitrary attributes attached to this resource)
is_default
boolean (Is this domain default)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "attributes": {
    },
  • "is_default": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get an environment domain

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
domainId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "project": "string",
  • "name": "string",
  • "registered_name": "string",
  • "attributes": {
    },
  • "is_default": true
}

Update an environment domain

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
domainId
required
string
Request Body schema: application/json
One of
object (Arbitrary attributes attached to this resource)
is_default
boolean (Is this domain default)

Responses

Request samples

Content type
application/json
Example
{
  • "attributes": {
    },
  • "is_default": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete an environment domain

Delete a single user-specified domain associated with an environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
domainId
required
string

Responses

Response samples

Content type
application/json
{
  • "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.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an SSL certificate

Add a single SSL certificate to a project.

Authorizations:
OAuth2
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)
is_invalid
boolean (Whether this certificate should be skipped during provisioning)

Responses

Request samples

Content type
application/json
{
  • "certificate": "string",
  • "key": "string",
  • "chain": [
    ],
  • "is_invalid": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get an SSL certificate

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

Authorizations:
OAuth2
path Parameters
projectId
required
string
certificateId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "certificate": "string",
  • "chain": [
    ],
  • "is_provisioned": true,
  • "is_invalid": true,
  • "is_root": true,
  • "domains": [
    ],
  • "auth_type": [
    ],
  • "issuer": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z"
}

Update an SSL certificate

Update a single SSL certificate associated with a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
certificateId
required
string
Request Body schema: application/json
chain
Array of strings (Certificate chain)
is_invalid
boolean (Whether this certificate should be skipped during provisioning)

Responses

Request samples

Content type
application/json
{
  • "chain": [
    ],
  • "is_invalid": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete an SSL certificate

Delete a single SSL certificate associated with a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
certificateId
required
string

Responses

Response samples

Content type
application/json
{
  • "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

Retrieve a list of objects representing the user-defined variables within a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a project variable

Add a variable to a project. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. See the Variables section in our documentation for more information.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
name
required
string (Name)
value
required
string (Value)
object (Arbitrary attributes attached to this resource)
is_json
boolean (The variable is a JSON string)
is_sensitive
boolean (The variable is sensitive)
visible_build
boolean (The variable is visible during build)
visible_runtime
boolean (The variable is visible at runtime)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a project variable

Retrieve a single user-defined project variable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectVariableId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true
}

Update a project variable

Update a single user-defined project variable. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. See the Variables section in our documentation for more information.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectVariableId
required
string
Request Body schema: application/json
name
string (Name)
object (Arbitrary attributes attached to this resource)
value
string (Value)
is_json
boolean (The variable is a JSON string)
is_sensitive
boolean (The variable is sensitive)
visible_build
boolean (The variable is visible during build)
visible_runtime
boolean (The variable is visible at runtime)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete a project variable

Delete a single user-defined project variable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectVariableId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Repository

The Git repository backing projects hosted on Platform.sh can be accessed in a read-only manner through the /projects/{projectId}/git/* family of endpoints. With these endpoints, you can retrieve objects from the Git repository in the same way that you would in a local environment.

Get a blob object

Retrieve, by hash, an object representing a blob in the repository backing a project. This endpoint allows direct read-only access to the contents of files in a repo. It returns the file in the content field of the response object, encoded according to the format in the encoding field, e.g. base64.

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryBlobId
required
string

Responses

Response samples

Content type
application/json
{
  • "sha": "string",
  • "size": 0,
  • "encoding": "base64",
  • "content": "string"
}

Get a commit object

Retrieve, by hash, an object representing a commit in the repository backing a project. This endpoint functions similarly to git cat-file -p <commit-id>. The returned object contains the hash of the Git tree that it belongs to, as well as the ID of parent commits.

The commit represented by a parent ID can be retrieved using this endpoint, while the tree state represented by this commit can be retrieved using the Get a tree object endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryCommitId
required
string

Responses

Response samples

Content type
application/json
{
  • "sha": "string",
  • "author": {
    },
  • "committer": {
    },
  • "message": "string",
  • "tree": "string",
  • "parents": [
    ]
}

Get list of repository refs

Retrieve a list of refs/* in the repository backing a project. This endpoint functions similarly to git show-ref, with each returned object containing a ref field with the ref's name, and an object containing the associated commit ID.

The returned commit ID can be used with the Get a commit object endpoint to retrieve information about that specific commit.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a ref object

Retrieve the details of a single refs object in the repository backing a project. This endpoint functions similarly to git show-ref <pattern>, although the pattern must be a full ref id, rather than a matching pattern.

NOTE: The {repositoryRefId} must be properly escaped. That is, the ref refs/heads/master is accessible via /projects/{projectId}/git/refs/heads%2Fmaster.

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryRefId
required
string

Responses

Response samples

Content type
application/json
{
  • "ref": "string",
  • "object": {
    },
  • "sha": "string"
}

Get a tree object

Retrieve, by hash, the tree state represented by a commit. The returned object's tree field contains a list of files and directories present in the tree.

Directories in the tree can be recursively retrieved by this endpoint through their hashes. Files in the tree can be retrieved by the Get a blob object endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryTreeId
required
string

Responses

Response samples

Content type
application/json
{
  • "sha": "string",
  • "tree": [
    ]
}

Third-Party Integrations

Platform.sh can easily integrate with many third-party services, including Git hosting services (GitHub, GitLab, and Bitbucket), health notification services (email, Slack, PagerDuty), performance analytics platforms (New Relic, Blackfire, Tideways), and webhooks.

For clarification about what information each field requires, see the External Integrations documentation. NOTE: The names of the CLI arguments listed in the documentation are not always named exactly the same as the required body fields in the API request.

Get list of existing integrations for a project

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Integrate project with a third-party service

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
One of
type
required
string (Integration type)
repository
required
string (The Bitbucket repository (in the form `user/repo`).)
fetch_branches
boolean (Whether or not to fetch branches.)
prune_branches
boolean (Whether or not to remove branches that disappeared remotely (requires `fetch_branches`).)
environment_init_resources
string (The resources used when initializing a new service)
Enum: "default" "manual" "minimum" "parent"
object or null (The OAuth2 consumer information (optional).)
object or null (The addon credential information (optional).)
build_pull_requests
boolean (Whether or not to build pull requests.)
resync_pull_requests
boolean (Whether or not pull request environment data should be re-synced on every build.)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "string",
  • "fetch_branches": true,
  • "prune_branches": true,
  • "environment_init_resources": "default",
  • "app_credentials": {
    },
  • "addon_credentials": {
    },
  • "repository": "string",
  • "build_pull_requests": true,
  • "resync_pull_requests": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get information about an existing third-party integration

Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "type": "string",
  • "fetch_branches": true,
  • "prune_branches": true,
  • "environment_init_resources": "default",
  • "app_credentials": {
    },
  • "addon_credentials": {
    },
  • "repository": "string",
  • "build_pull_requests": true,
  • "resync_pull_requests": true
}

Update an existing third-party integration

Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string
Request Body schema: application/json
One of
type
required
string (Integration type)
repository
required
string (The Bitbucket repository (in the form `user/repo`).)
fetch_branches
boolean (Whether or not to fetch branches.)
prune_branches
boolean (Whether or not to remove branches that disappeared remotely (requires `fetch_branches`).)
environment_init_resources
string (The resources used when initializing a new service)
Enum: "default" "manual" "minimum" "parent"
object or null (The OAuth2 consumer information (optional).)
object or null (The addon credential information (optional).)
build_pull_requests
boolean (Whether or not to build pull requests.)
resync_pull_requests
boolean (Whether or not pull request environment data should be re-synced on every build.)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "string",
  • "fetch_branches": true,
  • "prune_branches": true,
  • "environment_init_resources": "default",
  • "app_credentials": {
    },
  • "addon_credentials": {
    },
  • "repository": "string",
  • "build_pull_requests": true,
  • "resync_pull_requests": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete an existing third-party integration

Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Support

These endpoints can be used to retrieve information about support ticket priority and allow you to submit new ticket to the Platform.sh Support Team.

Create a new support ticket

Authorizations:
OAuth2
Request Body schema: application/json
subject
required
string

A title of the ticket.

description
required
string

The description body of the support ticket.

requester_id
string <uuid>

UUID of the ticket requester. Converted from the ZID value.

priority
string
Enum: "low" "normal" "high" "urgent"

A priority of the ticket.

subscription_id
string

see create()

affected_url
string <url>

see create().

followup_tid
string

The unique ID of the ticket which this ticket is a follow-up to.

category
string
Enum: "access" "billing_question" "complaint" "compliance_question" "configuration_change" "general_question" "incident_outage" "bug_report" "report_a_gui_bug" "onboarding" "close_my_account"

The category of the support ticket.

Array of objects

A list of attachments for the ticket.

collaborator_ids
Array of strings

A list of collaborators uuids for the ticket.

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "description": "string",
  • "requester_id": "5fe88a55-c92f-4e12-bd25-87bf15036ce9",
  • "priority": "low",
  • "subscription_id": "string",
  • "affected_url": "string",
  • "followup_tid": "string",
  • "category": "access",
  • "attachments": [
    ],
  • "collaborator_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ticket_id": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "type": "problem",
  • "subject": "string",
  • "description": "string",
  • "priority": "low",
  • "followup_tid": "string",
  • "status": "closed",
  • "recipient": "string",
  • "requester_id": "5fe88a55-c92f-4e12-bd25-87bf15036ce9",
  • "submitter_id": "7e359385-67b1-4c24-8530-73be9a04faec",
  • "assignee_id": "e209ca2d-190b-4818-b659-67d4ef4f1ce8",
  • "organization_id": "string",
  • "collaborator_ids": [
    ],
  • "has_incidents": true,
  • "due": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "subscription_id": "string",
  • "ticket_group": "string",
  • "support_plan": "string",
  • "affected_url": "string",
  • "queue": "string",
  • "issue_type": "string",
  • "resolution_time": "2019-08-24T14:15:22Z",
  • "response_time": "2019-08-24T14:15:22Z",
  • "project_url": "string",
  • "region": "string",
  • "category": "access",
  • "environment": "env_development",
  • "ticket_sharing_status": "ts_sent_to_platform",
  • "application_ticket_url": "string",
  • "infrastructure_ticket_url": "string",
  • "jira": [
    ]
}

Update a ticket

Authorizations:
OAuth2
path Parameters
ticket_id
required
string

The ID of the ticket

Request Body schema: application/json
status
string
Enum: "open" "solved"

The status of the support ticket.

collaborator_ids
Array of strings

A list of collaborators uuids for the ticket.

collaborators_replace
boolean
Default: null

Whether or not should replace ticket collaborators with the provided values. If false, the collaborators will be appended.

Responses

Request samples

Content type
application/json
{
  • "status": "open",
  • "collaborator_ids": [
    ],
  • "collaborators_replace": null
}

Response samples

Content type
application/json
{
  • "ticket_id": 0,
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "type": "problem",
  • "subject": "string",
  • "description": "string",
  • "priority": "low",
  • "followup_tid": "string",
  • "status": "closed",
  • "recipient": "string",
  • "requester_id": "5fe88a55-c92f-4e12-bd25-87bf15036ce9",
  • "submitter_id": "7e359385-67b1-4c24-8530-73be9a04faec",
  • "assignee_id": "e209ca2d-190b-4818-b659-67d4ef4f1ce8",
  • "organization_id": "string",
  • "collaborator_ids": [
    ],
  • "has_incidents": true,
  • "due": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "subscription_id": "string",
  • "ticket_group": "string",
  • "support_plan": "string",
  • "affected_url": "string",
  • "queue": "string",
  • "issue_type": "string",
  • "resolution_time": "2019-08-24T14:15:22Z",
  • "response_time": "2019-08-24T14:15:22Z",
  • "project_url": "string",
  • "region": "string",
  • "category": "access",
  • "environment": "env_development",
  • "ticket_sharing_status": "ts_sent_to_platform",
  • "application_ticket_url": "string",
  • "infrastructure_ticket_url": "string",
  • "jira": [
    ]
}

List support ticket priorities

Authorizations:
OAuth2
query Parameters
subscription_id
string

The ID of the subscription the ticket should be related to

category
string

The category of the support ticket.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List support ticket categories

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Environment

On Platform.sh, an environment encompasses a single instance of your entire application stack, the services used by the application, the application's data storage, and the environment's backups.

In general, an environment represents a single branch or merge request in the Git repository backing a project. It is a virtual cluster of read-only application and service containers with read-write mounts for application and service data.

On Platform.sh, the master branch is your production environment—thus, merging changes to master will put those changes to production.

Get list of project environments

Retrieve a list of a project's existing environments and the information associated with each environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an environment

Retrieve the details of a single existing environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "machine_name": "string",
  • "title": "string",
  • "attributes": {
    },
  • "type": "development",
  • "parent": "string",
  • "default_domain": "string",
  • "has_domains": true,
  • "clone_parent_on_create": true,
  • "deployment_target": "string",
  • "is_pr": true,
  • "status": "active",
  • "http_access": {
    },
  • "enable_smtp": true,
  • "restrict_robots": true,
  • "edge_hostname": "string",
  • "deployment_state": {
    },
  • "resources_overrides": {
    },
  • "last_active_at": "2019-08-24T14:15:22Z",
  • "last_backup_at": "2019-08-24T14:15:22Z",
  • "project": "string",
  • "is_main": true,
  • "is_dirty": true,
  • "has_code": true,
  • "head_commit": "string",
  • "merge_info": {
    },
  • "has_deployment": true
}

Update an environment

Update the details of a single existing environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
name
string (Name)
title
string (Title)
object (Arbitrary attributes attached to this resource)
type
string (The type of environment (`production`, `staging` or `development`). If not provided, a default will be calculated.)
Enum: "development" "production" "staging"
parent
string or null (Parent environment)
clone_parent_on_create
boolean (Clone data when creating that environment)
object (Http access permissions)
enable_smtp
boolean (Whether to configure SMTP for this environment.)
restrict_robots
boolean (Whether to restrict robots for this environment.)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "attributes": {
    },
  • "type": "development",
  • "parent": "string",
  • "clone_parent_on_create": true,
  • "http_access": {
    },
  • "enable_smtp": true,
  • "restrict_robots": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete an environment

Delete a specified environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Activate an environment

Set the specified environment's status to active

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Branch an environment

Create a new environment as a branch of the current environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
title
required
string (Title)
name
required
string (Name)
clone_parent
required
boolean (Clone data from the parent environment)
type
required
string (The type of environment (`staging` or `development`))
Enum: "development" "staging"

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "name": "string",
  • "clone_parent": true,
  • "type": "development"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Deactivate an environment

Destroy all services and data running on this environment so that only the Git branch remains. The environment can be reactivated later at any time; reactivating an environment will sync data from the parent environment and redeploy.

NOTE: ALL DATA IN THIS ENVIRONMENT WILL BE IRREVOCABLY LOST

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Initialize a new environment

Initialize and configure a new environment with an existing repository. The payload is the url of a git repository with a profile name:

{
    "repository": "git@github.com:platformsh/a-project-template.git@master",
    "profile": "Example Project",
    "files": [
      {
        "mode": 0600,
        "path": "config.json",
        "contents": "XXXXXXXX"
      }
    ]
}

It can optionally carry additional files that will be committed to the repository, the POSIX file mode to set on each file, and the base64-encoded contents of each file.

This endpoint can also add a second repository URL in the config parameter that will be added to the contents of the first. This allows you to put your application in one repository and the Platform.sh YAML configuration files in another.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
profile
required
string (Name of the profile to show in the UI)
repository
required
string (Repository to clone from)
config
required
string or null (Repository to clone the configuration files from)
required
Array of objects (A list of files to add to the repository during initialization)

Responses

Request samples

Content type
application/json
{
  • "profile": "string",
  • "repository": "string",
  • "config": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Merge an environment

Merge an environment into its parent. This means that code changes from the branch environment will be merged into the parent branch, and the parent branch will be rebuilt and deployed with the new code changes, retaining the existing data in the parent environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Pause an environment

Pause an environment, stopping all services and applications (except the router).

Development environments are often used for a limited time and then abandoned. To prevent unnecessary consumption of resources, development environments that haven't been redeployed in 14 days are automatically paused.

You can pause an environment manually at any time using this endpoint. Further information is available in our public documentation.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Redeploy an environment

Trigger the redeployment sequence of an environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Resume a paused environment

Resume a paused environment, restarting all services and applications.

Development environments that haven't been used for 14 days will be paused automatically. They can be resumed via a redeployment or manually using this endpoint or the CLI as described in the public documentation.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Synchronize a child environment with its parent

This synchronizes the code and/or data of an environment with that of its parent, then redeploys the environment. Synchronization is only possible if a branch has no unmerged commits and it can be fast-forwarded.

If data synchronization is specified, the data in the environment will be overwritten with that of its parent.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
synchronize_code
required
boolean (Synchronize code?)
rebase
required
boolean (Synchronize code by rebasing instead of merging)
synchronize_data
required
boolean (Synchronize data?)

Responses

Request samples

Content type
application/json
{
  • "synchronize_code": true,
  • "rebase": true,
  • "synchronize_data": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

List versions associated with the environment

List versions associated with the {environmentId} environment. At least one version always exists. When multiple versions exist, it means that multiple versions of an app are deployed. The deployment target type denotes whether staged deployment is supported.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create versions associated with the environment

Create versions associated with the {environmentId} environment. At least one version always exists. When multiple versions exist, it means that multiple versions of an app are deployed. The deployment target type denotes whether staged deployment is supported.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
object (Configuration about the traffic routed to this version)

Responses

Request samples

Content type
application/json
{
  • "routing": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

List the version

List the {versionId} version. A routing percentage for this version may be specified for staged rollouts (if the deployment target supports it).

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
versionId
required
string

Responses

Response samples

Content type
application/json
{
  • "commit": "string",
  • "locked": true,
  • "routing": {
    }
}

Update the version

Update the {versionId} version. A routing percentage for this version may be specified for staged rollouts (if the deployment target supports it).

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
versionId
required
string
Request Body schema: application/json
object (Configuration about the traffic routed to this version)

Responses

Request samples

Content type
application/json
{
  • "routing": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete the version

Delete the {versionId} version. A routing percentage for this version may be specified for staged rollouts (if the deployment target supports it).

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
versionId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Environment Backups

A snapshot is a complete backup of an environment, including all the persistent data from all services running in an environment and all files present in mounted volumes.

These endpoints can be used to trigger the creation of new snapshots, get information about existing snapshots, delete existing snapshots or restore a snapshot. More information about snapshots can be found in our Snapshot and Restore documentation.

Create snapshot of environment

Trigger a new snapshot of an environment to be created. See the Snapshot and Restore section of the documentation for more information.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
safe
required
boolean (Take a safe or a live backup)

Responses

Request samples

Content type
application/json
{
  • "safe": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get an environment's snapshot list

Retrieve a list of objects representing backups of this environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an environment snapshot's info

Get the details of a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
backupId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "attributes": {
    },
  • "status": "CREATED",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "index": 0,
  • "commit_id": "string",
  • "environment": "string",
  • "safe": true,
  • "size_of_volumes": 0,
  • "size_used": 0,
  • "restorable": true,
  • "automated": true
}

Delete an environment snapshot

Delete a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
backupId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Restore an environment snapshot

Restore a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
backupId
required
string
Request Body schema: application/json
environment_name
required
string or null (Environment name)
branch_from
required
string or null (Branch from)
restore_code
required
boolean (Whether we should restore the code or only the data)

Responses

Request samples

Content type
application/json
{
  • "environment_name": "string",
  • "branch_from": "string",
  • "restore_code": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Environment Variables

These endpoints manipulate user-defined variables which are bound to a specific environment, as well as (optionally) the children of an environment. These variables can be made available at both build time and runtime. For more information on environment variables, see the Variables section of the documentation.

Get list of environment variables

Retrieve a list of objects representing the user-defined variables within an environment.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add an environment variable

Add a variable to an environment. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. Additionally, the inheritability of an environment variable can be determined through the is_inheritable flag (default: true). See the Variables section in our documentation for more information.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
name
required
string (Name)
value
required
string (Value)
object (Arbitrary attributes attached to this resource)
is_json
boolean (The variable is a JSON string)
is_sensitive
boolean (The variable is sensitive)
visible_build
boolean (The variable is visible during build)
visible_runtime
boolean (The variable is visible at runtime)
is_enabled
boolean (The variable is enabled on this environment)
is_inheritable
boolean (The variable is inheritable to child environments)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true,
  • "is_enabled": true,
  • "is_inheritable": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get an environment variable

Retrieve a single user-defined environment variable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
variableId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true,
  • "project": "string",
  • "environment": "string",
  • "inherited": true,
  • "is_enabled": true,
  • "is_inheritable": true
}

Update an environment variable

Update a single user-defined environment variable. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. Additionally, the inheritability of an environment variable can be determined through the is_inheritable flag (default: true). See the Variables section in our documentation for more information.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
variableId
required
string
Request Body schema: application/json
name
string (Name)
object (Arbitrary attributes attached to this resource)
value
string (Value)
is_json
boolean (The variable is a JSON string)
is_sensitive
boolean (The variable is sensitive)
visible_build
boolean (The variable is visible during build)
visible_runtime
boolean (The variable is visible at runtime)
is_enabled
boolean (The variable is enabled on this environment)
is_inheritable
boolean (The variable is inheritable to child environments)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "attributes": {
    },
  • "value": "string",
  • "is_json": true,
  • "is_sensitive": true,
  • "visible_build": true,
  • "visible_runtime": true,
  • "is_enabled": true,
  • "is_inheritable": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete an environment variable

Delete a single user-defined environment variable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
variableId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Routing

These endpoints modify an environment's .platform/routes.yaml file. For routes to propagate to child environments, the child environments must be synchronized with their parent.

Warning: These endpoints create a new commit in the project repository. This may lead to merge conflicts if you are using an external Git provider through our integrations.

We strongly recommend that you specify your routes in your .platform/routes.yaml file if you use an external Git integration such as GitHub or GitLab.

More information about routing can be found in the Routes section of the documentation.

Get list of routes

Retrieve a list of objects containing route definitions for a specific environment. The definitions returned by this endpoint are those present in an environment's .platform/routes.yaml file.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new route

Add a new route to the specified environment. More information about how routes are defined can be found in the Routes section of the documentation.

This endpoint modifies an environment's .platform/routes.yaml file. For routes to propagate to child environments, the child environments must be synchronized with their parent.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
One of
type
required
string (Route type.)
Enum: "proxy" "redirect" "upstream"
to
required
string (Proxy destination)
primary
boolean or null (This route is the primary route of the environment)
id
string or null (Route Identifier)
production_url
string or null (How this URL route would look on production environment)
object (Arbitrary attributes attached to this resource)
object (TLS settings for the route.)

Responses

Request samples

Content type
application/json
Example
{
  • "primary": true,
  • "id": "string",
  • "production_url": "string",
  • "attributes": {
    },
  • "type": "proxy",
  • "tls": {
    },
  • "to": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a route's info

Get details of a route from an environment using the id of the entry retrieved by the Get environment routes list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
routeId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "primary": true,
  • "id": "string",
  • "production_url": "string",
  • "attributes": {
    },
  • "type": "proxy",
  • "tls": {
    },
  • "to": "string"
}

Update a route

Update a route in an environment using the id of the entry retrieved by the Get environment routes list endpoint.

This endpoint modifies an environment's .platform/routes.yaml file. For routes to propagate to child environments, the child environments must be synchronized with their parent.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
routeId
required
string
Request Body schema: application/json
One of
type
required
string (Route type.)
Enum: "proxy" "redirect" "upstream"
to
required
string (Proxy destination)
primary
boolean or null (This route is the primary route of the environment)
id
string or null (Route Identifier)
production_url
string or null (How this URL route would look on production environment)
object (Arbitrary attributes attached to this resource)
object (TLS settings for the route.)

Responses

Request samples

Content type
application/json
Example
{
  • "primary": true,
  • "id": "string",
  • "production_url": "string",
  • "attributes": {
    },
  • "type": "proxy",
  • "tls": {
    },
  • "to": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete a route

Remove a route from an environment using the id of the entry retrieved by the Get environment routes list endpoint.

This endpoint modifies an environment's .platform/routes.yaml file. For routes to propagate to child environments, the child environments must be synchronized with their parent.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
routeId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Source Operations

These endpoints interact with source code operations as defined in the source.operations key in a project's .platform.app.yaml configuration. More information on source code operations is available in our user documentation.

Trigger a source operation

This endpoint triggers a source code operation as defined in the source.operations key in a project's .platform.app.yaml configuration. More information on source code operations is available in our user documentation.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
operation
required
string (The name of the operation to execute)
required
object (The variables of the application.)

Responses

Request samples

Content type
application/json
{
  • "operation": "string",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

List source operations

Lists all the source operations, defined in .platform.app.yaml, that are available in an environment. More information on source code operations is available in our user documentation.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Runtime Operations

Execute a runtime operation

Execute a runtime operation on a currently deployed environment. This allows you to run one-off commands, such as rebuilding static assets on demand, by defining an operations key in a project's .platform.app.yaml configuration. More information on runtime operations is available in our user documentation.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
deploymentId
required
string
Request Body schema: application/json
service
required
string (The name of the application or worker to run the operation on)
operation
required
string (The name of the operation)

Responses

Request samples

Content type
application/json
{
  • "service": "string",
  • "operation": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Deployment

Get an environment's deployment information

Retrieve the read-only configuration of an environment's deployment. The returned information is everything required to recreate a project's current deployment.

More specifically, the objects returned by this endpoint contain the configuration derived from the repository's YAML configuration files: .platform.app.yaml, .platform/services.yaml, and .platform/routes.yaml.

Additionally, any values deriving from environment variables, the domains attached to a project, project access settings, etc. are included here.

This endpoint currently returns a list containing a single deployment configuration with an id of current. This may be subject to change in the future.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single environment deployment

Retrieve a single deployment configuration with an id of current. This may be subject to change in the future. Only current can be queried.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
deploymentId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "fingerprint": "string",
  • "cluster_name": "string",
  • "project_info": {
    },
  • "environment_info": {
    },
  • "deployment_target": "string",
  • "vpn": {
    },
  • "http_access": {
    },
  • "enable_smtp": true,
  • "restrict_robots": true,
  • "variables": [
    ],
  • "access": [
    ],
  • "subscription": {
    },
  • "services": {
    },
  • "routes": {
    },
  • "webapps": {
    },
  • "workers": {
    },
  • "container_profiles": {
    }
}

Project Activity

Get project activity log

Retrieve a project's activity log including logging actions in all environments within a project. This returns a list of objects with records of actions such as:

  • Commits being pushed to the repository
  • A new environment being branched out from the specified environment
  • A snapshot being created of the specified environment

The object includes a timestamp of when the action occurred (created_at), when the action concluded (updated_at), the current state of the action, the action's completion percentage (completion_percent), the environments it applies to and other related information in the payload.

The contents of the payload varies based on the type of the activity. For example:

  • An environment.branch action's payload can contain objects representing the environment's parent environment and the branching action's outcome.

  • An environment.push action's payload can contain objects representing the environment, the specific commits included in the push, and the user who pushed.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a project activity log entry

Retrieve a single activity log entry as specified by an id returned by the Get project activity log endpoint. See the documentation on that endpoint for details about the information this endpoint can return.

Authorizations:
OAuth2
path Parameters
projectId
required
string
activityId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "parameters": { },
  • "project": "string",
  • "integration": "string",
  • "environments": [
    ],
  • "state": "cancelled",
  • "result": "failure",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "completion_percent": 0,
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "timings": {
    },
  • "log": "string",
  • "payload": { },
  • "description": "string",
  • "text": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Cancel a project activity

Cancel a single activity as specified by an id returned by the Get project activity log endpoint.

Please note that not all activities are cancelable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
activityId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Environment Activity

Get environment activity log

Retrieve an environment's activity log. This returns a list of object with records of actions such as:

  • Commits being pushed to the repository
  • A new environment being branched out from the specified environment
  • A snapshot being created of the specified environment

The object includes a timestamp of when the action occurred (created_at), when the action concluded (updated_at), the current state of the action, the action's completion percentage (completion_percent), and other related information in the payload.

The contents of the payload varies based on the type of the activity. For example:

  • An environment.branch action's payload can contain objects representing the parent environment and the branching action's outcome.

  • An environment.push action's payload can contain objects representing the environment, the specific commits included in the push, and the user who pushed.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an environment activity log entry

Retrieve a single environment activity entry as specified by an id returned by the Get environment activities list endpoint. See the documentation on that endpoint for details about the information this endpoint can return.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
activityId
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "parameters": { },
  • "project": "string",
  • "integration": "string",
  • "environments": [
    ],
  • "state": "cancelled",
  • "result": "failure",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "completion_percent": 0,
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "timings": {
    },
  • "log": "string",
  • "payload": { },
  • "description": "string",
  • "text": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Cancel an environment activity

Cancel a single activity as specified by an id returned by the Get environment activities list endpoint.

Please note that not all activities are cancelable.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
activityId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Project Access

These endpoints can be used to manipulate the access control list at the project level. Users and roles defined here will apply globally to all environments within a project. For more fine-grained, environment-level access control, see the section entitled Environment Type Access.

Get a project's access control list Deprecated

Retrieve a list of objects specifying the users with access to a project and those users' roles.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a user to a project ACL Deprecated

Add a user to a project's access control list

Note:

For more granular control and invitation by email, use /invitations.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
role
required
string (Role)
Enum: "admin" "viewer"
user
string (User)
email
string (E-mail address)

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "email": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a single project ACL entry Deprecated

Retrieve the details of a user from a project's access control list using the id of the entry in the access control list retrieved with the Get project access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectAccessId
required
string

Responses

Response samples

Content type
application/json
{
  • "user": "string",
  • "role": "admin"
}

Update a project user's role Deprecated

Change the role of a user from a project's access control list using the id of the entry in the access control list retrieved with the Get project access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectAccessId
required
string
Request Body schema: application/json
role
string (Role)
Enum: "admin" "viewer"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Remove a user from a project Deprecated

Remove a user from a project's access control list using the id of the entry in the access control list retrieved with the Get project access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
projectAccessId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

List user access for a project

Returns a list of items representing the project access.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

query Parameters
page[size]
integer [ 1 .. 200 ]
Default: null

Determines the number of items to show.

page[before]
string

Shows 50 access items before the given cursor.

page[after]
string

Shows 50 access items after the given cursor.

sort
string
Example: sort=-updated_at

Allows sorting by a single field.
Use a dash ("-") to sort descending.
Supported fields: granted_at, updated_at.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Grant user access to a project

Grants one or more users access to a specific project.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
Array
user_id
required
string

ID of the user.

permissions
required
Array of strings (ProjectPermissions)
Items Enum: "admin" "viewer" "development:admin" "development:contributor" "development:viewer" "staging:admin" "staging:contributor" "staging:viewer" "production:admin" "production:contributor" "production:viewer"

An array of project permissions.

auto_add_member
boolean

If the specified user is not a member of the project's organization, add it automatically.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Get user access for a project

Retrieves the user's permissions for the current project.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "organization_id": "string",
  • "project_id": "string",
  • "project_title": "string",
  • "permissions": [
    ],
  • "granted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update user access for a project

Updates the user's permissions for the current project.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
permissions
required
Array of strings (ProjectPermissions)
Items Enum: "admin" "viewer" "development:admin" "development:contributor" "development:viewer" "staging:admin" "staging:contributor" "staging:viewer" "production:admin" "production:contributor" "production:viewer"

An array of project permissions.

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Remove user access for a project

Removes the user from the current project.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Environment Type

Environment Types is the way Platform.sh manages access. We currently have 3 enviroment types:

  • Development
  • Staging
  • Production

Each environment type will contain a group of users and their accesses. We manage access, adding, updating and removing users and their roles, here.

Each environemnt will have a type, pointing to one of these 3 environemnt types. See type in Environments.

In general:

  • Production will be reserved for the default branch, and cannot be set manually.
  • An environment can be set to be type staging or development manually and when branching.

Dedicated Generation 2 projects have different rules for environment types. If your project contains at least one of those Dedicated Generation 2 environments, the rules are slightly different:

  • All non-dedicated environment in your project are enforeced to be development.
  • Dedicated Generation 2 environments can be set either to Staging or Production.
  • The default branch is not considered to be a special case.

Get environment types

List all available environment types

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get environment type links

Lists the endpoints used to retrieve info about the environment type.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    }
}

Environment Type Access

These endpoints can be used to manipulate the access control list of a environment type at the environment type level—that is, users and roles defined here will apply specifically to a single environment type. See Environment Types

For more project-level access control, see the section entitled Project Access.

Get an environment type's access control list Deprecated

Retrieve a list of objects for users and their roles for the given environment type.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a user to an environment ACL Deprecated

Add a user to an environment type's access control list

Note:

For more granular control and invitation by email, use /invitations.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string
Request Body schema: application/json
role
required
string (Role)
Enum: "admin" "contributor" "viewer"
user
string (User)
email
string (E-mail address)

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "email": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a single environment type's ACL entry Deprecated

Retrieve the details of a user from an environment type's access control list using the id of the entry in the access control list retrieved with the Get environment type's access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string
environmentTypeAccessId
required
string

Responses

Response samples

Content type
application/json
{
  • "user": "string",
  • "role": "admin"
}

Update an environment type user's role Deprecated

Update the role of a user from an environment type's access control list using the id of the entry in the access control list retrieved with the Get environment access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string
environmentTypeAccessId
required
string
Request Body schema: application/json
role
string (Role)
Enum: "admin" "contributor" "viewer"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Remove a user from an environment type Deprecated

Remove a user from an environment type's access control list. using the id of the entry in the access control list retrieved with the Get environment type access control list endpoint.

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentTypeId
required
string
environmentTypeAccessId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Environment Access

DEPRECATED

This endpoint is currently maintained for backwards compatibility, but it has been deprecated and its behaviour has changed, please, use Environment Type Access instead.

The access is no longer associated with an environment, but with environment types. Doing any operation against an environment access endpoint will be the same as doing said operation against the environment type access endpoint. For example, if you list or modify an access in an environment of type development, you will be effectively changing the environment type; all the environments of type development would be affected.

Invitations

Invite user to an organization by email

Creates an invitation to an organization for a user with the specified email address.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
email
required
string <email>

The email address of the invitee.

permissions
required
Array of strings
Items Enum: "billing" "plans" "members" "projects:create" "projects:list"

The permissions the invitee should be given on the organization.

force
boolean

Whether to cancel any pending invitation for the specified invitee, and create a new invitation.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "permissions": [
    ],
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "state": "pending",
  • "organization_id": "string",
  • "email": "user@example.com",
  • "owner": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "permissions": [
    ]
}

List invitations to an organization

Returns a list of invitations to an organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

query Parameters
object (StringFilter)

Allows filtering by state of the invtations: "pending" (default), "error".

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Enum: "updated_at" "-updated_at"

Allows sorting by a single field.
Use a dash ("-") to sort descending.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cancel a pending invitation to an organization

Cancels the specified invitation.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

invitation_id
required
string

The ID of the invitation.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Invite user to a project by email

Creates an invitation to a project for a user with the specified email address.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
email
required
string <email>

The email address of the invitee.

role
string
Default: null
Enum: "admin" "viewer"

The role the invitee should be given on the project.

Array of objects

Specifying the role on each environment type.

Array of objects
Deprecated

(Deprecated, use permissions instead) Specifying the role on each environment.

force
boolean

Whether to cancel any pending invitation for the specified invitee, and create a new invitation.

Responses

Request samples

Content type
application/json
{
  • "role": "admin",
  • "email": "user@example.com",
  • "permissions": [
    ],
  • "environments": [
    ],
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "state": "pending",
  • "project_id": "string",
  • "role": "admin",
  • "email": "user@example.com",
  • "owner": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "environments": [
    ]
}

List invitations to a project

Returns a list of invitations to a project.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

query Parameters
object (StringFilter)

Allows filtering by state of the invtations: "pending" (default), "error".

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Enum: "updated_at" "-updated_at"

Allows sorting by a single field.
Use a dash ("-") to sort descending.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cancel a pending invitation to a project

Cancels the specified invitation.

Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

invitation_id
required
string

The ID of the invitation.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Organizations

User organizations

Retrieves organizations that the specified user is a member of.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

query Parameters
object (StringFilter)

Allows filtering by id using one or more operators.

object (StringFilter)

Allows filtering by status using one or more operators.
Defaults to filter[status][in]=active,restricted,suspended.

object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Example: sort=-updated_at

Allows sorting by a single field.
Use a dash ("-") to sort descending.
Supported fields: name, created_at, updated_at.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

List organizations

Non-admin users will only see organizations they are members of.

Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by id using one or more operators.

object (StringFilter)

Allows filtering by owner_id using one or more operators.

object (StringFilter)

Allows filtering by name using one or more operators.

object (StringFilter)

Allows filtering by label using one or more operators.

object (ArrayFilter)

Allows filtering by capabilites using one or more operators.

object (StringFilter)

Allows filtering by status using one or more operators.
Defaults to filter[status][in]=active,restricted,suspended.

object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Example: sort=-updated_at

Allows sorting by a single field.
Use a dash ("-") to sort descending.
Supported fields: name, created_at, updated_at.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "items": [
    ],
  • "_links": {
    }
}

Create organization

Creates a new organization.

Authorizations:
OAuth2
Request Body schema: application/json
name
required
string

A unique machine name representing the organization.

label
required
string

The human-readable label of the organization.

owner_id
string <uuid>

ID of the owner.

country
string <= 2 characters

The organization country (2-letter country code).

Responses

Request samples

Content type
application/json
{
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "name": "string",
  • "label": "string",
  • "country": "st"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Get organization

Retrieves the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update organization

Updates the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
name
string

A unique machine name representing the organization.

label
string

The human-readable label of the organization.

country
string <= 2 characters

The organization country (2-letter country code).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "country": "st"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Delete organization

Deletes the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Responses

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

List organization members

Accessible to organization owners and members with the "manage members" permission.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
object (ArrayFilter)

Allows filtering by permissions using one or more operators.

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Example: sort=-updated_at

Allows sorting by a single field.
Use a dash ("-") to sort descending.
Supported fields: created_at, updated_at.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "items": [
    ],
  • "_links": {
    }
}

Create organization member

Creates a new organization member.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
user_id
required
string <uuid>

ID of the user.

permissions
Array of strings (Permissions)
Items Enum: "billing" "members" "plans" "projects:create" "projects:list"

An array of permissions. The owner's permissions will be an empty list, as owners have all permissions automatically.

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "permissions": [
    ],
  • "owner": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Get organization member

Retrieves the specified organization member.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "permissions": [
    ],
  • "owner": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update organization member

Updates the specified organization member.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
permissions
Array of strings (Permissions)
Items Enum: "billing" "members" "plans" "projects:create" "projects:list"

An array of permissions. The owner's permissions will be an empty list, as owners have all permissions automatically.

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "permissions": [
    ],
  • "owner": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Delete organization member

Deletes the specified organization member.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

API Tokens

List a user's API tokens

Retrieves a list of API tokens associated with a single user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an API token

Creates an API token

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
name
required
string

The token name.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an API token

Retrieves the specified API token.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

token_id
required
string <uuid>

The ID of the token.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete an API token

Deletes an API token

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

token_id
required
string <uuid>

The ID of the token.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Connections

List federated login connections

Retrieves a list of connections associated with a single user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a federated login connection

Retrieves the specified connection.

Authorizations:
OAuth2
path Parameters
provider
required
string

The name of the federation provider.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "provider": "string",
  • "is_mandatory": true,
  • "subject": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a federated login connection

Deletes the specified connection.

Authorizations:
OAuth2
path Parameters
provider
required
string

The name of the federation provider.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

MFA

Multi-factor authentication (MFA) requires the user to present two (or more) types of evidence (or factors) to prove their identity.

For example, the evidence might be a password and a device-generated code, which show the user has the knowledge factor ("something you know") as well as the possession factor ("something you have"). In this way MFA offers good protection against the compromise of any single factor, such as a stolen password.

Using the MFA API you can set up time-based one-time passcodes (TOTP), which can be generated on a single registered device ("something you have") such as a mobile phone.

Get information about TOTP enrollment

Retrieves TOTP enrollment information.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "issuer": "http://example.com",
  • "account_name": "string",
  • "secret": "string",
  • "qr_code": "string"
}

Confirm TOTP enrollment

Confirms the given TOTP enrollment.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
secret
required
string

The secret seed for the enrollment

passcode
required
string

TOTP passcode for the enrollment

Responses

Request samples

Content type
application/json
{
  • "secret": "string",
  • "passcode": "string"
}

Response samples

Content type
application/json
{
  • "recovery_codes": [
    ]
}

Withdraw TOTP enrollment

Withdraws from the TOTP enrollment.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Re-create recovery codes

Re-creates recovery codes for the MFA enrollment.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "recovery_codes": [
    ]
}

Users

Get current logged-in user info Deprecated

Retrieve information about the currently logged-in user (the user associated with the access token).

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "username": "string",
  • "display_name": "string",
  • "status": 0,
  • "mail": "user@example.com",
  • "ssh_keys": [
    ],
  • "has_key": true,
  • "projects": [
    ],
  • "sequence": 0,
  • "roles": [
    ],
  • "picture": "string",
  • "tickets": { },
  • "trial": true,
  • "current_trial": [
    ]
}

Check if phone verification is required

Find out if the current logged in user requires phone verification to create projects.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "verify_phone": true
}

Check if verification is required

Find out if the current logged in user requires verification (phone or staff) to create projects.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "state": true,
  • "type": "string"
}

Get the current user

Retrieves the current user, determined from the used access token.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deactivated": true,
  • "namespace": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "email_verified": true,
  • "first_name": "string",
  • "last_name": "string",
  • "picture": "http://example.com",
  • "company": "string",
  • "website": "http://example.com",
  • "country": "st",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "consented_at": "2019-08-24T14:15:22Z",
  • "consent_method": "opt-in"
}

Get a user by email

Retrieves a user matching the specified email address.

Authorizations:
OAuth2
path Parameters
email
required
string <email>
Example: hello@example.com

The user's email address.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deactivated": true,
  • "namespace": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "email_verified": true,
  • "first_name": "string",
  • "last_name": "string",
  • "picture": "http://example.com",
  • "company": "string",
  • "website": "http://example.com",
  • "country": "st",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "consented_at": "2019-08-24T14:15:22Z",
  • "consent_method": "opt-in"
}

Get a user by username

Retrieves a user matching the specified username.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: platform-sh

The user's username.

Responses

Response samples

Content type
application/json
No sample

Get a user

Retrieves the specified user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deactivated": true,
  • "namespace": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "email_verified": true,
  • "first_name": "string",
  • "last_name": "string",
  • "picture": "http://example.com",
  • "company": "string",
  • "website": "http://example.com",
  • "country": "st",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "consented_at": "2019-08-24T14:15:22Z",
  • "consent_method": "opt-in"
}

Update a user

Updates the specified user.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
username
string

The user's username.

first_name
string

The user's first name.

last_name
string

The user's last name.

picture
string <uri>

The user's picture.

company
string

The user's company.

website
string <uri>

The user's website.

country
string = 2 characters

The user's country (2-letter country code).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deactivated": true,
  • "namespace": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "email_verified": true,
  • "first_name": "string",
  • "last_name": "string",
  • "picture": "http://example.com",
  • "company": "string",
  • "website": "http://example.com",
  • "country": "st",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "consented_at": "2019-08-24T14:15:22Z",
  • "consent_method": "opt-in"
}

Reset email address

Requests a reset of the user's email address. A confirmation email will be sent to the new address when the request is accepted.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
email_address
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email_address": "user@example.com"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Reset user password

Requests a reset of the user's password. A password reset email will be sent to the user when the request is accepted.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

User Access

List project access for a user

Returns a list of items representing the user's project access.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

query Parameters
filter[organization_id]
string

Allows filtering by organization_id.

page[size]
integer [ 1 .. 200 ]
Default: null

Determines the number of items to show.

page[before]
string

Shows 50 access items before the given cursor.

page[after]
string

Shows 50 access items after the given cursor.

sort
string
Example: sort=-updated_at

Allows sorting by a single field.
Use a dash ("-") to sort descending.
Supported fields: project_title, granted_at, updated_at.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Grant project access to a user

Adds the user to one or more specified projects.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Request Body schema: application/json
Array
project_id
required
string

ID of the project.

permissions
required
Array of strings (ProjectPermissions)
Items Enum: "admin" "viewer" "development:admin" "development:contributor" "development:viewer" "staging:admin" "staging:contributor" "staging:viewer" "production:admin" "production:contributor" "production:viewer"

An array of project permissions.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Get project access for a user

Retrieves the user's permissions for the current project.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

project_id
required
string

The ID of the project.

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "organization_id": "string",
  • "project_id": "string",
  • "project_title": "string",
  • "permissions": [
    ],
  • "granted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update project access for a user

Updates the user's permissions for the current project.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

project_id
required
string

The ID of the project.

Request Body schema: application/json
permissions
required
Array of strings (ProjectPermissions)
Items Enum: "admin" "viewer" "development:admin" "development:contributor" "development:viewer" "staging:admin" "staging:contributor" "staging:viewer" "production:admin" "production:contributor" "production:viewer"

An array of project permissions.

Responses

Request samples

Content type
application/json
{
  • "permissions": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Remove project access for a user

Removes the user from the current project.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

project_id
required
string

The ID of the project.

Responses

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

User Profiles

List user profiles

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "profiles": [
    ],
  • "_links": {
    }
}

Get a single user profile

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "display_name": "string",
  • "email": "user@example.com",
  • "username": "string",
  • "type": "user",
  • "picture": "string",
  • "company_type": "string",
  • "company_name": "string",
  • "currency": "string",
  • "vat_number": "string",
  • "company_role": "string",
  • "website_url": "string",
  • "new_ui": true,
  • "ui_colorscheme": "string",
  • "default_catalog": "string",
  • "project_options_url": "string",
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "security_contact": "user@example.com",
  • "current_trial": {
    }
}

Update a user profile

Update a user profile, supplying one or more key/value pairs to to change.

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

Request Body schema: application/json
display_name
string

The user's display name.

username
string

The user's username.

current_password
string

The user's current password.

password
string

The user's new password.

company_type
string

The company type.

company_name
string

The name of the company.

vat_number
string

The vat number of the user.

company_role
string

The role of the user in the company.

marketing
boolean

Flag if the user agreed to receive marketing communication.

ui_colorscheme
string

The user's chosen color scheme for user interfaces. Available values are 'light' and 'dark'.

default_catalog
string

The URL of a catalog file which overrides the default.

project_options_url
string

The URL of an account-wide project options file.

picture
string

Url of the user's picture.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "username": "string",
  • "current_password": "string",
  • "password": "string",
  • "company_type": "string",
  • "company_name": "string",
  • "vat_number": "string",
  • "company_role": "string",
  • "marketing": true,
  • "ui_colorscheme": "string",
  • "default_catalog": "string",
  • "project_options_url": "string",
  • "picture": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "display_name": "string",
  • "email": "user@example.com",
  • "username": "string",
  • "type": "user",
  • "picture": "string",
  • "company_type": "string",
  • "company_name": "string",
  • "currency": "string",
  • "vat_number": "string",
  • "company_role": "string",
  • "website_url": "string",
  • "new_ui": true,
  • "ui_colorscheme": "string",
  • "default_catalog": "string",
  • "project_options_url": "string",
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "security_contact": "user@example.com",
  • "current_trial": {
    }
}

Get a user address

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

Responses

Response samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string",
  • "metadata": {
    }
}

Update a user address

Update a user address, supplying one or more key/value pairs to to change.

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

Request Body schema: application/json
country
string <ISO ALPHA-2>

Two-letter country codes are used to represent countries and states

name_line
string

The full name of the user

premise
string

Premise (i.e. Apt, Suite, Bldg.)

sub_premise
string

Sub Premise (i.e. Suite, Apartment, Floor, Unknown.

thoroughfare
string

The address of the user

administrative_area
string <ISO ALPHA-2>

The administrative area of the user address

sub_administrative_area
string

The sub-administrative area of the user address

locality
string

The locality of the user address

dependent_locality
string

The dependant_locality area of the user address

postal_code
string

The postal code area of the user address

Responses

Request samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string"
}

Response samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string",
  • "metadata": {
    }
}

Create a user profile picture

Authorizations:
OAuth2
path Parameters
uuid
required
string <uuid>

The uuid of the user

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Delete a user profile picture

Authorizations:
OAuth2
path Parameters
uuid
required
string <uuid>

The uuid of the user

Responses

SSH Keys

Get an SSH key

Authorizations:
OAuth2
path Parameters
key_id
required
integer

The ID of the ssh key.

Responses

Response samples

Content type
application/json
{
  • "key_id": 0,
  • "uid": 0,
  • "fingerprint": "string",
  • "title": "string",
  • "value": "string",
  • "changed": "string"
}

Delete an SSH key

Authorizations:
OAuth2
path Parameters
key_id
required
integer

The ID of the ssh key.

Responses

Add a new public SSH key to a user

Authorizations:
OAuth2
Request Body schema: application/json
value
required
string

The value of the ssh key.

title
string

The title of the ssh key.

uuid
string

The uuid of the user.

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "title": "string",
  • "uuid": "string"
}

Response samples

Content type
application/json
{
  • "key_id": 0,
  • "uid": 0,
  • "fingerprint": "string",
  • "title": "string",
  • "value": "string",
  • "changed": "string"
}

Teams

List teams

Retrieves a list of teams.

Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by organization_id using one or more operators.

object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Enum: "label" "-label" "created_at" "-created_at" "updated_at" "-updated_at"

Allows sorting by a single field.
Use a dash ("-") to sort descending.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0,
  • "_links": {
    }
}

Create team

Creates a new team.

Authorizations:
OAuth2
Request Body schema: application/json
organization_id
required
string <ulid>

The ID of the parent organization.

label
required
string

The human-readable label of the team.

project_permissions
Array of strings

Project permissions that are granted to the team.

Responses

Request samples

Content type
application/json
{
  • "organization_id": "string",
  • "label": "string",
  • "project_permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "label": "string",
  • "project_permissions": [
    ],
  • "counts": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get team

Retrieves the specified team.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "label": "string",
  • "project_permissions": [
    ],
  • "counts": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update team

Updates the specified team.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

Request Body schema: application/json
label
string

The human-readable label of the team.

project_permissions
Array of strings

Project permissions that are granted to the team.

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "project_permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "label": "string",
  • "project_permissions": [
    ],
  • "counts": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete team

Deletes the specified team.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

List team members

Retrieves a list of users associated with a single team.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

query Parameters
page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at"

Allows sorting by a single field.
Use a dash ("-") to sort descending.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Create team member

Creates a new team member.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

Request Body schema: application/json
user_id
required
string <uuid>

ID of the user.

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get team member

Retrieves the specified team member.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete team member

Deletes the specified team member.

Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

User teams

Retrieves teams that the specified user is a member of.

Authorizations:
OAuth2
path Parameters
user_id
required
string <uuid>
Example: d81c8ee2-44b3-429f-b944-a33ad7437690

The ID of the user.

query Parameters
object (StringFilter)

Allows filtering by organization_id using one or more operators.

object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

page[size]
integer [ 1 .. 100 ]
Default: null

Determines the number of items to show.

page[before]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

page[after]
string

Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.

sort
string
Enum: "created_at" "-created_at" "updated_at" "-updated_at"

Allows sorting by a single field.
Use a dash ("-") to sort descending.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0,
  • "_links": {
    }
}

Plans

List available plans

Retrieve information about plans and pricing on Platform.sh.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "plans": [
    ],
  • "_links": {
    }
}

References

List referenced users

Retrieves a list of users referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the _links object with a key like ref:users:0.

Authorizations:
OAuth2
query Parameters
in
required
string

The list of comma-separated user IDs generated by a trusted service.

sig
required
string

The signature of this request generated by a trusted service.

Responses

Response samples

Content type
application/json
{}

List referenced teams

Retrieves a list of teams referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the _links object with a key like ref:teams:0.

Authorizations:
OAuth2
query Parameters
in
required
string

The list of comma-separated team IDs generated by a trusted service.

sig
required
string

The signature of this request generated by a trusted service.

Responses

Response samples

Content type
application/json
{
  • "01FVMKN9KHVWWVY488AVKDWHR3": {
    }
}

List referenced organizations

Retrieves a list of organizations referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the _links object with a key like ref:organizations:0.

Authorizations:
OAuth2
query Parameters
in
required
string

The list of comma-separated organization IDs generated by a trusted service.

sig
required
string

The signature of this request generated by a trusted service.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Subscriptions

Each project is represented by a subscription that holds the plan information. These endpoints can be used to go to a larger plan, add more storage, or subscribe to optional features.

List subscriptions

Retrieves subscriptions for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[status]
string
Enum: "active" "provisioning" "provisioning failure" "suspended" "deleted"

The status of the subscription.

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Create subscription

Creates a subscription for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
project_region
required
string

The machine name of the region where the project is located. Cannot be changed after project creation.

plan
string (PlanType)
Enum: "development" "standard" "medium" "large" "xlarge" "2xlarge" "4xlarge" "8xlarge"

The plan type of the subscription.

project_title
string

The name given to the project. Appears as the title in the UI.

options_url
string

The URL of the project options file.

default_branch
string

The default Git branch name for the project.

environments
integer

The maximum number of active environments on the project.

storage
integer

The total storage available to each environment, in MiB. Only multiples of 1024 are accepted as legal values.

Responses

Request samples

Content type
application/json
{
  • "plan": "development",
  • "project_region": "string",
  • "project_title": "string",
  • "options_url": "string",
  • "default_branch": "string",
  • "environments": 0,
  • "storage": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "owner_info": {
    },
  • "vendor": "string",
  • "plan": "string",
  • "environments": 0,
  • "storage": 0,
  • "user_licenses": 0,
  • "project_id": "string",
  • "project_endpoint": "string",
  • "project_title": "string",
  • "project_region": "string",
  • "project_region_label": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "agency_site": true,
  • "invoiced": true,
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ]
}

Get subscription

Retrieves a subscription for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

subscription_id
required
string

The ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "owner_info": {
    },
  • "vendor": "string",
  • "plan": "string",
  • "environments": 0,
  • "storage": 0,
  • "user_licenses": 0,
  • "project_id": "string",
  • "project_endpoint": "string",
  • "project_title": "string",
  • "project_region": "string",
  • "project_region_label": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "agency_site": true,
  • "invoiced": true,
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ]
}

Update subscription

Updates a subscription for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

subscription_id
required
string

The ID of the subscription.

Request Body schema: application/json
plan
required
string (PlanType)
Enum: "development" "standard" "medium" "large" "xlarge" "2xlarge" "4xlarge" "8xlarge"

The plan type of the subscription.

environments
integer

The maximum number of environments which can be provisioned on the project.

storage
integer

The total storage available to each environment, in MiB.

big_dev
string

The development environment plan.

big_dev_service
string

The development service plan.

backups
string

The backups plan.

observability_suite
string

The observability suite plan.

blackfire
string

The blackfire plan.

Responses

Request samples

Content type
application/json
{
  • "plan": "development",
  • "environments": 0,
  • "storage": 0,
  • "big_dev": "string",
  • "big_dev_service": "string",
  • "backups": "string",
  • "observability_suite": "string",
  • "blackfire": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "owner_info": {
    },
  • "vendor": "string",
  • "plan": "string",
  • "environments": 0,
  • "storage": 0,
  • "user_licenses": 0,
  • "project_id": "string",
  • "project_endpoint": "string",
  • "project_title": "string",
  • "project_region": "string",
  • "project_region_label": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "agency_site": true,
  • "invoiced": true,
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ]
}

Delete subscription

Deletes a subscription for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

subscription_id
required
string

The ID of the subscription.

Responses

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Estimate the price of a new subscription

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

query Parameters
plan
required
string

The plan type of the subscription.

environments
required
integer

The maximum number of environments which can be provisioned on the project.

storage
required
integer

The total storage available to each environment, in MiB.

user_licenses
required
integer

The number of user licenses.

format
string
Enum: "formatted" "complex"

The format of the estimation output.

Responses

Response samples

Content type
application/json
{
  • "plan": "string",
  • "user_licenses": "string",
  • "environments": "string",
  • "storage": "string",
  • "total": "string",
  • "options": { }
}

Checks if the user is able to create a new project.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Responses

Response samples

Content type
application/json
{
  • "can_create": true,
  • "message": "string",
  • "required_action": {
    }
}

Estimate the price of a subscription

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

subscription_id
required
string

The ID of the subscription.

query Parameters
plan
required
string

The plan type of the subscription.

environments
integer

The maximum number of environments which can be provisioned on the project.

storage
integer

The total storage available to each environment, in MiB.

user_licenses
integer

The number of user licenses.

format
string
Enum: "formatted" "complex"

The format of the estimation output.

Responses

Response samples

Content type
application/json
{
  • "plan": "string",
  • "user_licenses": "string",
  • "environments": "string",
  • "storage": "string",
  • "total": "string",
  • "options": { }
}

Orders

These endpoints can be used to retrieve order information from our billing system. Here you can view information about your bill for our services, include the billed amount and a link to a PDF of the bill.

List orders

Retrieves orders for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[status]
string
Enum: "completed" "past_due" "pending" "canceled" "payment_failed_soft_decline" "payment_failed_hard_decline"

The status of the order.

filter[total]
integer

The total of the order.

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Get order

Retrieves an order for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

order_id
required
string

The ID of the order.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "completed",
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "address": {
    },
  • "vat_number": "string",
  • "billing_period_start": "2019-08-24T14:15:22Z",
  • "billing_period_end": "2019-08-24T14:15:22Z",
  • "billing_period_duration": 0,
  • "paid_on": "2019-08-24T14:15:22Z",
  • "total": 0,
  • "components": {
    },
  • "currency": "string",
  • "invoice_url": "string",
  • "_links": {
    }
}

Invoices

These endpoints can be used to retrieve invoices from our billing system. An invoice of type "invoice" is generated automatically every month, if the customer has active projects. Invoices of type "credit_memo" are a result of manual action when there was a refund or an invoice correction.

List invoices

Retrieves a list of invoices for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[status]
string
Enum: "paid" "charged_off" "pending" "refunded" "canceled" "refund_pending"

The status of the invoice.

filter[type]
string
Enum: "credit_memo" "invoice"

The invoice type. Use invoice for standard invoices, credit_memo for refund/credit invoices.

filter[order_id]
string

The order id of Invoice.

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get invoice

Retrieves an invoice for the specified organization.

Authorizations:
OAuth2
path Parameters
invoice_id
required
string

The ID of the invoice.

organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "invoice_number": "string",
  • "type": "invoice",
  • "order_id": "string",
  • "related_invoice_id": "string",
  • "status": "paid",
  • "owner": "string",
  • "invoice_date": "2019-08-24T14:15:22Z",
  • "invoice_due": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "changed": "2019-08-24T14:15:22Z",
  • "company": "string",
  • "total": 0,
  • "address": {
    },
  • "notes": "string",
  • "invoice_pdf": {
    }
}

Vouchers

These endpoints can be used to retrieve vouchers associated with a particular user as well as apply a voucher to a particular user.

List vouchers

Retrieves vouchers for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "vouchers_total": "string",
  • "vouchers_applied": "string",
  • "vouchers_remaining_balance": "string",
  • "currency": "string",
  • "vouchers": [
    ],
  • "_links": {
    }
}

Apply voucher

Applies a voucher for the specified organization, and refreshes the currently open order.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
code
required
string

The voucher code.

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/problem+json
{
  • "status": "string",
  • "message": "string",
  • "code": 0,
  • "detail": { },
  • "title": "string"
}

Records

These endpoints retrieve information about which plans were assigned to a particular project at which time.

List plan records

Retrieves plan records for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[subscription_id]
string

The ID of the subscription

filter[plan]
string
Enum: "development" "standard" "medium" "large" "xlarge" "2xlarge"

The plan type of the subscription.

filter[status]
string
Enum: "active" "suspended"

The status of the plan record.

filter[start]
string <date-time>

The start of the observation period for the record. E.g. filter[start]=2018-01-01 will display all records that were active (i.e. did not end) on 2018-01-01

filter[end]
string <date-time>

The end of the observation period for the record. E.g. filter[end]=2018-01-01 will display all records that were active on (i.e. they started before) 2018-01-01

filter[started_at]
string <date-time>

The record's start timestamp. You can use this filter to list records started after, or before a certain time. E.g. filter[started_at][value]=2020-01-01&filter[started_at][operator]=>

filter[ended_at]
string <date-time>

The record's end timestamp. You can use this filter to list records ended after, or before a certain time. E.g. filter[ended_at][value]=2020-01-01&filter[ended_at][operator]=>

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

List usage records

Retrieves usage records for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[subscription_id]
string

The ID of the subscription

filter[usage_group]
string
Enum: "storage" "environments" "user_licenses"

Filter records by the type of usage.

filter[start]
string <date-time>

The start of the observation period for the record. E.g. filter[start]=2018-01-01 will display all records that were active (i.e. did not end) on 2018-01-01

filter[started_at]
string <date-time>

The record's start timestamp. You can use this filter to list records started after, or before a certain time. E.g. filter[started_at][value]=2020-01-01&filter[started_at][operator]=>

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Profiles

Get address

Retrieves the address for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

Responses

Response samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string"
}

Update address

Updates the address for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
country
string <ISO ALPHA-2>

Two-letter country codes are used to represent countries and states

name_line
string

The full name of the user

premise
string

Premise (i.e. Apt, Suite, Bldg.)

sub_premise
string

Sub Premise (i.e. Suite, Apartment, Floor, Unknown.

thoroughfare
string

The address of the user

administrative_area
string <ISO ALPHA-2>

The administrative area of the user address

sub_administrative_area
string

The sub-administrative area of the user address

locality
string

The locality of the user address

dependent_locality
string

The dependant_locality area of the user address

postal_code
string

The postal code area of the user address

Responses

Request samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string"
}

Response samples

Content type
application/json
{
  • "country": "string",
  • "name_line": "string",
  • "premise": "string",
  • "sub_premise": "string",
  • "thoroughfare": "string",
  • "administrative_area": "string",
  • "sub_administrative_area": "string",
  • "locality": "string",
  • "dependent_locality": "string",
  • "postal_code": "string"
}

Get profile

Retrieves the profile for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "display_name": "string",
  • "email": "user@example.com",
  • "username": "string",
  • "type": "user",
  • "picture": "string",
  • "company_type": "string",
  • "company_name": "string",
  • "currency": "string",
  • "vat_number": "string",
  • "company_role": "string",
  • "website_url": "string",
  • "new_ui": true,
  • "ui_colorscheme": "string",
  • "default_catalog": "string",
  • "project_options_url": "string",
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "security_contact": "user@example.com",
  • "current_trial": {
    }
}

Update profile

Updates the profile for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

Request Body schema: application/json
default_catalog
string

The URL of a catalog file which overrides the default.

project_options_url
string <uri>

The URL of an organization-wide project options file.

security_contact
string <email>

The e-mail address of a contact to whom security notices will be sent.

company_name
string

The company name.

vat_number
string

The VAT number of the company.

billing_contact
string <email>

The e-mail address of a contact to whom billing notices will be sent.

Responses

Request samples

Content type
application/json
{
  • "default_catalog": "string",
  • "project_options_url": "http://example.com",
  • "security_contact": "user@example.com",
  • "company_name": "string",
  • "vat_number": "string",
  • "billing_contact": "user@example.com"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "display_name": "string",
  • "email": "user@example.com",
  • "username": "string",
  • "type": "user",
  • "picture": "string",
  • "company_type": "string",
  • "company_name": "string",
  • "currency": "string",
  • "vat_number": "string",
  • "company_role": "string",
  • "website_url": "string",
  • "new_ui": true,
  • "ui_colorscheme": "string",
  • "default_catalog": "string",
  • "project_options_url": "string",
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "security_contact": "user@example.com",
  • "current_trial": {
    }
}

Project Discovery

Locate user projects Deprecated

Returns a paginated list of all the projects associated with a given UUID. The returned information includes each project's respective endpoint and management console URLs, as well as information about the project owner.

Authorizations:
OAuth2
query Parameters
filter[owner]
string

The UUID of the owner.

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "projects": [
    ],
  • "_links": {
    }
}

Locate a single project

Returns a project's endpoint and management console URLs, as well as information about the project owner.

Authorizations:
OAuth2
path Parameters
projectId
required
string

The ID of the project

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "endpoint": "string",
  • "ui": "string",
  • "subscription_id": 0,
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "owner_info": {
    }
}

Regions

List available regions

Retrieves the list of available regions for the specified organization.

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ID of the organization.
Prefix with name= to retrieve the organization by name instead.

query Parameters
filter[zone]
string

Geographical zone of the region.

filter[available]
string

Value 0 displays only disabled regions. Value 1 displays only enabled ones.

filter[private]
string

Value 0 displays only public regions. Value 1 displays only private ones.

page
integer <int32>

Page to be displayed. Defaults to 1.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Project Settings

These endpoints can be used to retrieve and manipulate project-level settings. Only the initialize property can be set by end users. It is used to initialize a project from an existing Git repository.

The other properties can only be set by a privileged user.

Get list of project settings

Retrieve the global settings for a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "initialize": { },
  • "product_name": "string",
  • "product_code": "string",
  • "ui_uri_template": "string",
  • "variables_prefix": "string",
  • "bot_email": "string",
  • "application_config_file": "string",
  • "project_config_dir": "string",
  • "use_drupal_defaults": true,
  • "use_legacy_subdomains": true,
  • "development_service_size": "2XL",
  • "development_application_size": "2XL",
  • "enable_certificate_provisioning": true,
  • "certificate_style": "ecdsa",
  • "certificate_renewal_activity": true,
  • "development_domain_template": "string",
  • "enable_state_api_deployments": true,
  • "temporary_disk_size": 0,
  • "cron_minimum_interval": 0,
  • "cron_maximum_jitter": 0,
  • "concurrency_limits": {
    },
  • "flexible_build_cache": true,
  • "strict_configuration": true,
  • "has_sleepy_crons": true,
  • "crons_in_git": true,
  • "custom_error_template": "string",
  • "app_error_page_template": "string",
  • "environment_name_strategy": "hash",
  • "data_retention": {
    },
  • "enable_codesource_integration_push": true,
  • "enforce_mfa": true,
  • "systemd": true,
  • "router_gen2": true,
  • "chorus": {
    },
  • "build_resources": {
    },
  • "outbound_restrictions_default_policy": "allow",
  • "self_upgrade": true,
  • "additional_hosts": {
    },
  • "max_allowed_routes": 0,
  • "max_allowed_redirects_paths": 0,
  • "enable_incremental_backups": true,
  • "sizing_api_enabled": true,
  • "enable_cache_grace_period": true,
  • "enable_zero_downtime_deployments": true,
  • "enable_admin_agent": true,
  • "certifier_url": "string",
  • "centralized_permissions": true,
  • "glue_server_max_request_size": 0,
  • "persistent_endpoints_ssh": true,
  • "persistent_endpoints_ssl_certificates": true,
  • "enable_disk_health_monitoring": true,
  • "enable_paused_environments": true,
  • "enable_unified_configuration": true,
  • "enable_routes_tracing": true,
  • "image_deployment_validation": true,
  • "support_generic_images": true
}

Update a project setting

Update one or more project-level settings.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
initialize
object (Initialization key)
object (Chorus)
object (Build Resources)

Responses

Request samples

Content type
application/json
{
  • "initialize": { },
  • "chorus": { },
  • "build_resources": { }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Deployment Target

Platform.sh is capable of deploying the production environments of projects in multiple topologies: both in clusters of containers, and as dedicated virtual machines. This is an internal API that can only be used by privileged users.

Get project deployment target info

The deployment target information for the project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project deployment target

Set the deployment target information for a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
One of
type
required
string (The type of the deployment target.)
Enum: "dedicated" "enterprise" "local"
name
required
string (The name of the deployment target.)
enforced_mounts
object (Mounts which are always injected into pushed (e.g. enforce /var/log to be a local mount).)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "dedicated",
  • "name": "string",
  • "enforced_mounts": { }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Get a single project deployment target

Get a single deployment target configuration of a project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
deploymentTargetConfigurationId
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "type": "dedicated",
  • "name": "string",
  • "deploy_host": "string",
  • "deploy_port": 0,
  • "ssh_host": "string",
  • "hosts": [
    ],
  • "auto_mounts": true,
  • "excluded_mounts": [
    ],
  • "enforced_mounts": { },
  • "auto_crons": true,
  • "auto_nginx": true,
  • "maintenance_mode": true,
  • "guardrails_phase": 0
}

Update a project deployment

Authorizations:
OAuth2
path Parameters
projectId
required
string
deploymentTargetConfigurationId
required
string
Request Body schema: application/json
One of
type
required
string (The type of the deployment target.)
Enum: "dedicated" "enterprise" "local"
name
required
string (The name of the deployment target.)
enforced_mounts
object (Mounts which are always injected into pushed (e.g. enforce /var/log to be a local mount).)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "dedicated",
  • "name": "string",
  • "enforced_mounts": { }
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

Delete a single project deployment target

Delete a single deployment target configuration associated with a specific project.

Authorizations:
OAuth2
path Parameters
projectId
required
string
deploymentTargetConfigurationId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}

System Information

These endpoints can be used to retrieve low-level information and interact with the core component of Platform.sh infrastructure.

This is an internal API that can only be used by privileged users.

Get information about the Git server.

Output information for the project.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "image": "string",
  • "started_at": "2019-08-24T14:15:22Z"
}

Restart the Git server

Force the Git server to restart.

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "code": 0
}