diff --git a/shared/pages/api-internal.html b/shared/pages/api-internal.html new file mode 100644 index 0000000000..a1f7ed5290 --- /dev/null +++ b/shared/pages/api-internal.html @@ -0,0 +1,6864 @@ + + + + + + Upsun.com Rest API + + + + + + + + + + + + +
Upsun logo
API docs by Redocly

Upsun.com Rest API (1.0)

Download OpenAPI specification:

URL: https://upsun.com/contact-us/ Terms of Service

Introduction

Upsun, formerly 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 Upsun 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.

+

In order to use the API you will first need to have an Upsun account +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.upsun.com/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.upsun.com/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.upsun.com/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.

+

Organizations

[Internal] Retrieve organization SSO configuration.

Retrieve SSO configuration for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "provider_type": "google",
  • "domain": "string",
  • "organization_id": "string",
  • "enforced": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Create organization SSO configuration.

Create SSO configuration for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
Request Body schema: application/json
One of
provider_type
string
Value: "google"

SSO provider type.

+
domain
string

Google hosted domain.

+

Responses

Request samples

Content type
application/json
{
  • "provider_type": "google",
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "provider_type": "google",
  • "domain": "string",
  • "organization_id": "string",
  • "enforced": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Delete organization SSO configuration.

Delete SSO configuration for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

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

[Internal] Enable organization SSO configuration.

Enable SSO configuration enforcement for the specified organization's members.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "provider_type": "google",
  • "domain": "string",
  • "organization_id": "string",
  • "enforced": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Disable organization SSO configuration.

Disable SSO configuration enforcement for the specified organization's members.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "provider_type": "google",
  • "domain": "string",
  • "organization_id": "string",
  • "enforced": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Revoke all the organization users tokens

Revoke access tokens for all the members of the given organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

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

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 type using one or more operators.

+
object (StringFilter)

Allows filtering by vendor 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, label, created_at, updated_at.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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 type 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 (StringFilter)

[Internal] Allows filtering by netsuite_id using one or more operators.

+
object (StringFilter)

Allows filtering by vendor 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, label, created_at, updated_at.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Create organization

Creates a new organization.

+
Authorizations:
OAuth2
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
required
type
string
Enum: "fixed" "flexible"

The type of the organization.

+
owner_id
string <uuid>

ID of the owner.

+
name
string

A unique machine name representing the organization.

+
label
required
string

The human-readable label of the organization.

+
country
string <= 2 characters

The organization country (2-letter country code).

+
capabilities
Array of strings unique

[Internal] The organization capabilities.

+
netsuite_id
string

[Internal] The Netsuite ID.

+
billing_account_id
string

[Internal] The Billing Account ID.

+
billing_legacy
boolean

[Internal] Whether the account is billed with the legacy system.

+
security_contact
string <email>

The security contact email address for the organization.

+
notes
string

[Internal] The internal notes for the organization.

+
status
string
Enum: "active" "restricted" "suspended"

[Internal] The status of the organization.

+

Responses

Request samples

Content type
application/json
{
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
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).

+
capabilities
Array of strings unique

[Internal] The organization capabilities.

+
vendor
string

[Internal] The vendor.

+
netsuite_id
string

[Internal] The Netsuite ID.

+
billing_account_id
string

[Internal] The Billing Account ID.

+
billing_legacy
boolean

[Internal] Whether the account is billed with the legacy system.

+
security_contact
string <email>

The security contact email address for the organization.

+
notes
string

[Internal] The internal notes for the organization.

+
status
string
Enum: "active" "restricted" "suspended"

[Internal] The status of the organization.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "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.

+
query Parameters
force
boolean

[Internal] Skip additional checks and force deletion.

+
skip_billing
boolean

[Internal] Skip deleting the billing data in Accounts.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

[Internal] Transfer organization

Transfers the organization to different owner.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

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

ID of the owner.

+

Responses

Request samples

Content type
application/json
{
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Debug organization access

Outputs member access info from Auth and Organizations, and whether it matches.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "grants": {
    },
  • "match": true
}

[Internal] List all organization members

Retrieves a list of members across all organizations.

+
Authorizations:
OAuth2
query Parameters
object (ArrayFilter)

Allows filtering by permissions using one or more operators.

+
object (DateTimeFilter)

Allows filtering by created_at 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
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": {
    }
}

Organization Members

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

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

ID of the user.

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

The organization member permissions.

+

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": [
    ],
  • "level": "admin",
  • "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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_id": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "permissions": [
    ],
  • "level": "admin",
  • "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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

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

The organization member permissions.

+

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": [
    ],
  • "level": "admin",
  • "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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Organization 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 (OrganizationPermissions)
Items Enum: "admin" "billing" "plans" "members" "project: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"
}

Organization Projects

[Internal] List all projects

Retrieves a list of projects across organizations.

+
Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by id using one or more operators.

+
object (StringFilter)

Allows filtering by organization_id using one or more operators.

+
object (StringFilter)

Allows filtering by subscription_id using one or more operators.

+
object (StringFilter)

Allows filtering by vendor using one or more operators.

+
object (StringFilter)

Allows filtering by region using one or more operators.

+
object (StringFilter)

Allows filtering by title using one or more operators.

+
object (StringFilter)

Allows filtering by type using one or more operators.

+
object (StringFilter)

Allows filtering by plan using one or more operators.

+
object (BooleanFilter)

Allows filtering by locked using one or more operators.

+
object (BooleanFilter)

Allows filtering by agency_site using one or more operators.

+
object (StringFilter)

Allows filtering by dedicated_tag using one or more operators.

+
object (StringFilter)

Allows filtering by billing_account_id using one or more operators.

+
object (StringFilter)

Allows filtering by status using one or more operators.

+
object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

+
object (DateTimeFilter)

Allows filtering by created_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: id, region, title, type, plan, status, created_at, updated_at.

+

Responses

Response samples

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

List projects

Retrieves a list of projects for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
query Parameters
object (StringFilter)

Allows filtering by id using one or more operators.

+
object (StringFilter)

Allows filtering by title using one or more operators.

+
object (StringFilter)

Allows filtering by status using one or more operators.

+
object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

+
object (DateTimeFilter)

Allows filtering by created_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: id, region, title, type, plan, status, created_at, updated_at.

+

Responses

Response samples

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

Create project

Creates a new project in the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
Request Body schema: application/json
required
organization_id
string (OrganizationID)

The ID of the organization.

+
region
required
string (RegionID)

The machine name of the region where the project is located.

+
title
string (ProjectTitle)

The title of the project.

+
type
string (ProjectType)
Enum: "grid" "dedicated"

The type of projects.

+
plan
string (ProjectPlan)

The project plan.

+
default_branch
string (ProjectDefaultBranch)

Default branch.

+
cse_notes
string (ProjectCSENotes)

CSE notes.

+
dedicated_tag
string (ProjectDedicatedTag)

Dedicated tag.

+
edgee_org_id
string (EdgeeOrgID)

[Internal] The organization id of the edgee service.

+
edgee_project_id
string (EdgeeProjectID)

[Internal] The project id of the edgee service.

+

Responses

Request samples

Content type
application/json
{
  • "organization_id": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "default_branch": "string",
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Get project

Retrieves the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Update project

Updates the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
Request Body schema: application/json
title
string (ProjectTitle)

The title of the project.

+
plan
string (ProjectPlan)

The project plan.

+
timezone
string (ProjectTimeZone)

Timezone of the project.

+
cse_notes
string (ProjectCSENotes)

CSE notes.

+
dedicated_tag
string (ProjectDedicatedTag)

Dedicated tag.

+
edgee_org_id
string (EdgeeOrgID)

[Internal] The organization id of the edgee service.

+
edgee_project_id
string (EdgeeProjectID)

[Internal] The project id of the edgee service.

+
billing_account_id
string (BillingAccountID)

[Internal] The billing account related to the project.

+

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "plan": "string",
  • "timezone": "string",
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Delete project

Deletes the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

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

[Internal] Suspend project

Suspends the specified active project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Reume project

Resumes the specified suspended project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Lock project

Locks the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Unlock project

Unlocks the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Sync project

Pushes information about the specified project to its git server.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "organization_id": "string",
  • "subscription_id": "string",
  • "vendor": "string",
  • "region": "string",
  • "title": "string",
  • "type": "grid",
  • "plan": "string",
  • "timezone": "string",
  • "default_branch": "string",
  • "status": "requested",
  • "options_url": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "support_tier": "string",
  • "options_custom": { },
  • "trial_plan": true,
  • "project_ui": "string",
  • "locked": true,
  • "cse_notes": "string",
  • "dedicated_tag": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string",
  • "billing_account_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Transfer project

Transfers the specified project to another organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

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

The ID of the organization.

+
keep_users
boolean

Whether the project's users should be retained (and added to the destination organization).

+

Responses

Request samples

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

Response samples

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

[Internal] Clone project

Requests the cloning of the specified project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
Request Body schema: application/json
required
title
string (ProjectTitle)

The title of the project.

+
region
string

The machine name of the region where the project is to be cloned.

+
exclude_envs
Array of strings

The environment names which needs to be excluded.

+
include_envs
Array of strings

The environment names which needs to be included.

+
skip_migrate_access
boolean

Whether to skip the access migration.

+

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "region": "string",
  • "exclude_envs": [
    ],
  • "include_envs": [
    ],
  • "skip_migrate_access": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "project_id": "string",
  • "status": "string",
  • "options": { },
  • "clone": { },
  • "progress": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    },
  • "activities": {
    },
  • "debug": { }
}

Query project carbon emissions metrics

Queries the carbon emission data for the specified project using the supplied parameters.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
query Parameters
object (DateTimeFilter)

The start of the time frame for the query. Inclusive.

+
object (DateTimeFilter)

The end of the time frame for the query. Exclusive.

+
interval
string
Enum: "day" "month" "year"

The interval by which the query groups the results. of the time frame for the query. Exclusive.

+

Responses

Response samples

Content type
application/json
{
  • "project_id": "string",
  • "project_title": "string",
  • "meta": {
    },
  • "values": [
    ],
  • "total": 0
}

Add-ons

Get add-ons

Retrieves information about the add-ons for an organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "available": {
    },
  • "current": {
    },
  • "upgrades_available": {
    }
}

[Internal] Update add-ons

Updates the add-ons for an organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
support_level
string
Enum: "" "standard"

The support level for the organization.

+
user_management
string
Enum: "standard" "advanced"

The user management level for the organization.

+

Responses

Request samples

Content type
application/json
{
  • "support_level": "",
  • "user_management": "standard"
}

Response samples

Content type
application/json
{
  • "available": {
    },
  • "current": {
    },
  • "upgrades_available": {
    }
}

[Internal] List project add-ons

Retrieves the specified project's add-ons.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
query Parameters
object (StringFilter)

Allows filtering by id using one or more operators.

+
object (StringFilter)

Allows filtering by type using one or more operators.

+
object (StringFilter)

Allows filtering by status using one or more operators.

+
object (DateTimeFilter)

Allows filtering by updated_at using one or more operators.

+

Responses

Response samples

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

[Internal] Create project add-on

Creates a new project add-on.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
Request Body schema: application/json
required
type
required
string (AddonType)

The type of the add-on.

+
sku
required
string (ProjectAddonSKU)

The SKU of the add-on.

+

Responses

Request samples

Content type
application/json
Example
{
  • "type": "storage",
  • "quantity": 1024
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "project_id": "string",
  • "type": "string",
  • "status": "requested",
  • "title": "string",
  • "unit": "string",
  • "allowed_values": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    },
  • "quantity": 0
}

[Internal] Get project add-on

Retrieves the specified project's add-on.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
addon_id
required
string

The ID of the add-on.

+

Responses

Response samples

Content type
application/json
{
  • "id": "abc",
  • "project_id": "p1",
  • "type": "storage",
  • "status": "active",
  • "quantity": 2048,
  • "title": "Extra storage",
  • "unit": "MB",
  • "allowed_values": [
    ],
  • "_links": {
    }
}

[Internal] Update project add-on

Updates the specified project's add-on.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
addon_id
required
string

The ID of the add-on.

+
Request Body schema: application/json
One of
quantity
required
integer (ProjectAddonQuantity)

The quantity of the add-on.

+

Responses

Request samples

Content type
application/json
Example
{
  • "quantity": 2048
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "project_id": "string",
  • "type": "string",
  • "status": "requested",
  • "title": "string",
  • "unit": "string",
  • "allowed_values": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    },
  • "quantity": 0
}

[Internal] Delete project add-on

Deletes the specified project's add-on.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
project_id
required
string

The ID of the project.

+
addon_id
required
string

The ID of the add-on.

+

Responses

Response samples

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

Project

Project Overview

On Upsun, 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.

+
+

[Internal] Get all projects

Retrieve a list of projects

+
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new project

Create a new project

+
Authorizations:
OAuth2
Request Body schema: application/json
required
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
title
required
string (Title)

The title of the project

+
description
string (Description)

The description of the project

+
default_branch
string or null (Default branch)

The default branch of the project

+
timezone
required
string (Timezone)

Timezone of the project

+
region
required
string (Region)

The region of the project

+
default_domain
string or null (Default domain)

The default domain of the project

+

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
}

Get a project

Retrieve the details of a single project.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "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
required
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
title
string (Title)

The title of the project

+
description
string (Description)

The description of the project

+
default_branch
string or null (Default branch)

The default branch of the project

+
timezone
string (Timezone)

Timezone of the project

+
region
string (Region)

The region of the project

+
default_domain
string or null (Default domain)

The default domain of the project

+

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": {
    },
  • "logs_forwarding": {
    },
  • "guaranteed_resources": {
    },
  • "images": {
    },
  • "instance_limit": 0,
  • "build_resources": {
    },
  • "data_retention": {
    },
  • "autoscaling": {
    },
  • "integrations": {
    }
}

[Internal] Update project capabilities

Update project capabilites, enabling and disabling them.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
object (ProjectCapabilitiesPatch)

Responses

Request samples

Content type
application/json
{ }

Response samples

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

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 +Upsun, 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
required
One of
name
required
string (Domain name)
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
is_default
boolean (Is Default)

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
{
  • "id": "string",
  • "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
required
One of
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
is_default
boolean (Is Default)

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
required
One of
name
required
string (Domain name)
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
is_default
boolean (Is Default)

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
{
  • "id": "string",
  • "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
required
One of
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
is_default
boolean (Is Default)

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. You can now list and modify certificate provisioners +using the /projects/{projectId}/provisioners and +/projects/{projectId}/provisioners/{certificateProvisionerDocumentId} +endpoints. For more information, see our +Third-party TLS certificate +documentation. These endpoints are not for managing certificates +that are automatically supplied by Upsun 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
required
certificate
required
string (Certificate)

The PEM-encoded certificate

+
key
required
string (Private Key)

The PEM-encoded private key

+
chain
Array of strings (Certificate chain)

The certificate chain

+
is_invalid
boolean (Is Invalid)

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
{
  • "id": "string",
  • "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
required
chain
Array of strings (Certificate chain)

The certificate chain

+
is_invalid
boolean (Is Invalid)

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
}

[Internal] Get list of (internal) SSL certificates

Retrieve a list of objects representing the (internal) SSL certificates +associated with a project. +Internal SSL certificates are signed by the project's own Certificate Authority.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Get an (internal) SSL certificate

Retrieve information about a single (internal) SSL certificate +associated with a project.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
internalCertificateId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "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"
}

[Internal] Delete an (internal) SSL certificate

Delete a single (internal) SSL certificate associated with a project.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
internalCertificateId
required
string

Responses

Response samples

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

list-projects-provisioners

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get-projects-provisioners

Authorizations:
OAuth2
path Parameters
projectId
required
string
certificateProvisionerDocumentId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "directory_url": "string",
  • "email": "string",
  • "eab_kid": "string",
  • "eab_hmac_key": "string"
}

update-projects-provisioners

Authorizations:
OAuth2
path Parameters
projectId
required
string
certificateProvisionerDocumentId
required
string
Request Body schema: application/json
required
directory_url
string (ACME directory url)

The URL to the ACME directory

+
email
string (Contacted email address)

The email address for contact information

+
eab_kid
string or null (EAB Key identifier)

The key identifier for Entity Attestation Binding

+
eab_hmac_key
string or null (EAB HMAC Key)

The Keyed-'Hashing Message Authentication Code' for Entity Attestation Binding

+

Responses

Request samples

Content type
application/json
{
  • "directory_url": "string",
  • "email": "string",
  • "eab_kid": "string",
  • "eab_hmac_key": "string"
}

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
required
name
required
string (Name)

Name of the variable

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
value
required
string (Value)

Value of the variable

+
is_json
boolean (Is JSON)

The variable is a JSON string

+
is_sensitive
boolean (Is Sensitive)

The variable is sensitive

+
visible_build
boolean (Visible during build)

The variable is visible during build

+
visible_runtime
boolean (Visible at runtime)

The variable is visible at runtime

+
application_scope
Array of strings (Application Scope)

Applications that have access to this variable

+

Responses

Request samples

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

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
{
  • "id": "string",
  • "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,
  • "application_scope": [
    ]
}

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
required
name
string (Name)

Name of the variable

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
value
string (Value)

Value of the variable

+
is_json
boolean (Is JSON)

The variable is a JSON string

+
is_sensitive
boolean (Is Sensitive)

The variable is sensitive

+
visible_build
boolean (Visible during build)

The variable is visible during build

+
visible_runtime
boolean (Visible at runtime)

The variable is visible at runtime

+
application_scope
Array of strings (Application Scope)

Applications that have access to this variable

+

Responses

Request samples

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

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

+

[Internal] List of available git endpoints

Returns a list of available git endpoints.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{ }

[Internal] Retrieve a list of blob objects

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new blob

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
encoding
string (Encoding)
Enum: "base64" "utf-8"

The encoding of the contents

+
content
required
string (Content)

The contents

+

Responses

Request samples

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

Response samples

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

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
{
  • "id": "string",
  • "sha": "string",
  • "size": 0,
  • "encoding": "base64",
  • "content": "string"
}

[Internal] Retrieve a list of commit objects

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new commit

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
object (Author)

The information about the author

+
object (Committer)

The information about the committer

+
message
required
string (Message)

The commit message

+
tree
required
string (Tree identifier)

The identifier of the tree

+
parents
required
Array of strings (Parent identifiers)

The identifiers of the parents of the commit

+

Responses

Request samples

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

Response samples

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

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
{
  • "id": "string",
  • "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
[
  • {
    }
]

[Internal] Create a new ref

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
ref
required
string (Name)

The name of the reference

+
sha
required
string (SHA)

The commit sha of the ref

+

Responses

Request samples

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

Response samples

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

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
{
  • "id": "string",
  • "ref": "string",
  • "object": {
    },
  • "sha": "string"
}

[Internal] Update a ref

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryRefId
required
string
Request Body schema: application/json
required
sha
string (SHA)

The commit sha of the ref

+

Responses

Request samples

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

Response samples

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

[Internal] Delete a ref

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryRefId
required
string

Responses

Response samples

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

[Internal] Retrive a list of tags in the repository

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new tag

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
tag
required
string (Tag name)

The tag name

+
object (Tagger)

The information about the tagger

+
message
required
string (Tag message)

The tag message

+
required
object (Object)

The information about the object the tag points to

+

Responses

Request samples

Content type
application/json
{
  • "tag": "string",
  • "tagger": {
    },
  • "message": "string",
  • "object": {
    }
}

Response samples

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

[Internal] Get the details of a single tag

Authorizations:
OAuth2
path Parameters
projectId
required
string
repositoryTagId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sha": "string",
  • "tag": "string",
  • "tagger": {
    },
  • "message": "string",
  • "object": {
    }
}

[Internal] Retrive a list of trees

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new tree

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
required
Array of objects (Tree items)

The tree items

+
base_tree
string or null (Base tree)

The base tree to use while creating this tree

+

Responses

Request samples

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

Response samples

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

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
{
  • "id": "string",
  • "sha": "string",
  • "tree": [
    ]
}

Third-Party Integrations

Upsun 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
required
One of
type
required
string (Integration type)
fetch_branches
boolean (Fetch Branches)

Whether or not to fetch branches.

+
prune_branches
boolean (Prune Branches)

Whether or not to remove branches that disappeared remotely (requires fetch_branches).

+
environment_init_resources
string (Environment Init Resources)
Enum: "default" "manual" "minimum" "parent"

The resources used when initializing a new service

+
object or null (OAuth2 consumer)

The OAuth2 consumer information (optional).

+
object or null (Addon credential)

The addon credential information (optional).

+
repository
required
string (Bitbucket repository)

The Bitbucket repository (in the form user/repo).

+
build_pull_requests
boolean (Build pull requests)

Whether or not to build pull requests.

+
pull_requests_clone_parent_data
boolean (Clone parent data)

Whether or not to clone parent data when building merge requests.

+
resync_pull_requests
boolean (Sync environment data)

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,
  • "pull_requests_clone_parent_data": 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
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "fetch_branches": true,
  • "prune_branches": true,
  • "environment_init_resources": "default",
  • "app_credentials": {
    },
  • "addon_credentials": {
    },
  • "repository": "string",
  • "build_pull_requests": true,
  • "pull_requests_clone_parent_data": 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
required
One of
type
required
string (Integration type)
fetch_branches
boolean (Fetch Branches)

Whether or not to fetch branches.

+
prune_branches
boolean (Prune Branches)

Whether or not to remove branches that disappeared remotely (requires fetch_branches).

+
environment_init_resources
string (Environment Init Resources)
Enum: "default" "manual" "minimum" "parent"

The resources used when initializing a new service

+
object or null (OAuth2 consumer)

The OAuth2 consumer information (optional).

+
object or null (Addon credential)

The addon credential information (optional).

+
repository
required
string (Bitbucket repository)

The Bitbucket repository (in the form user/repo).

+
build_pull_requests
boolean (Build pull requests)

Whether or not to build pull requests.

+
pull_requests_clone_parent_data
boolean (Clone parent data)

Whether or not to clone parent data when building merge requests.

+
resync_pull_requests
boolean (Sync environment data)

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,
  • "pull_requests_clone_parent_data": 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 Upsun Support Team.

+

[Internal] Return a token for use with zendesk messaging

Authorizations:
OAuth2

Responses

Response samples

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

[Internal] List support ticket comments

Authorizations:
OAuth2
query Parameters
filter[ticket_id]
integer

The ID of the ticket.

+
filter[comment_id]
integer

The ID of the comment.

+
filter[author_id]
string

The author id of the commenter.

+
filter[created_at]
integer

Time and date of comment creation.

+
filter[public]
string

If the comment is public it is set to 1.

+
page
integer <int32>

Page to be displayed. Defaults to 1.

+
all
string

[Internal] Add this parameter with whichever value to display all projects, otherwise, only projects owned by current user will be displayed (admins only).

+

Responses

Response samples

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

[Internal] Create a new support ticket comment

Authorizations:
OAuth2
Request Body schema: application/json
ticket_id
integer

The id of the ticket.

+
body
string

The body of the ticket comment.

+
author_id
string

The ID of the author of the comment

+
public
string

1 if the comment is public and therefore should be displayed to nonadmin users.

+
Array of objects

A list of attachments for the ticket.

+

Responses

Request samples

Content type
application/json
{
  • "ticket_id": 0,
  • "body": "string",
  • "author_id": "string",
  • "public": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "ticket_id": 0,
  • "comment_id": 0,
  • "body": "string",
  • "author_id": "string",
  • "created_at": 0,
  • "public": "string",
  • "attachments": [
    ]
}

[Internal] Get the first comment of a support ticket

Authorizations:
OAuth2
path Parameters
ticket_id
required
string

The ID of the ticket

+

Responses

Response samples

Content type
application/json
{
  • "ticket_id": 0,
  • "comment_id": 0,
  • "body": "string",
  • "author_id": "string",
  • "created_at": 0,
  • "public": "string",
  • "attachments": [
    ]
}

[Internal] List support ticket attachments

Authorizations:
OAuth2
path Parameters
ticket_id
required
string

The ID of the ticket

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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()

+
organization_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",
  • "organization_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": [
    ],
  • "zd_ticket_url": "string"
}

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": [
    ],
  • "zd_ticket_url": "string"
}

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
query Parameters
subscription_id
string

The ID of the subscription the ticket should be related to

+
organization_id
string

The ID of the organization the ticket should be related to

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Environment

On Upsun, 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 Upsun, the default branch is your production environment—thus, +merging changes to this branch 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
{
  • "id": "string",
  • "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,
  • "has_remote": true,
  • "status": "active",
  • "http_access": {
    },
  • "enable_smtp": true,
  • "restrict_robots": true,
  • "edge_hostname": "string",
  • "deployment_state": {
    },
  • "sizing": {
    },
  • "resources_overrides": {
    },
  • "max_instance_count": 0,
  • "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_staged_activities": true,
  • "can_rolling_deploy": true,
  • "supports_rolling_deployments": true,
  • "has_code": true,
  • "head_commit": "string",
  • "merge_info": {
    },
  • "has_deployment": true,
  • "supports_restrict_robots": 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
required
name
string (Name)

The name of the environment

+
title
string (Title)

The title of the environment

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
type
string (Type)
Enum: "development" "production" "staging"

The type of environment (production, staging or development), if not provided, a default will be calculated

+
parent
string or null (Parent environment)

The name of the parent environment

+
clone_parent_on_create
boolean (Clone parent on create)

Clone data when creating that environment

+
object (HTTP access permissions)

The HTTP access permissions for this environment

+
enable_smtp
boolean (Enable SMTP)

Whether to configure SMTP for this environment

+
restrict_robots
boolean (Restrict robots)

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
Request Body schema: application/json
required
required
object or null (Resources)

Responses

Request samples

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

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
required
title
required
string (Title)
name
required
string (Name)
clone_parent
required
boolean (Clone parent)

Clone data from the parent environment

+
type
required
string (Type)
Enum: "development" "staging"

The type of environment (staging or development)

+
required
object or null (Resources)

Responses

Request samples

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

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
}

Deploy an environment

Trigger a controlled manual deployment +to release all the staged changes

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
required
strategy
required
string (Deployment strategy)
Enum: "rolling" "stopstart"

The deployment strategy (rolling or stopstart)

+

Responses

Request samples

Content type
application/json
{
  • "strategy": "rolling"
}

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 Upsun +YAML configuration files in another.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
required
profile
required
string (Profile)

Name of the profile to show in the UI

+
repository
required
string (Repository)

Repository to clone from

+
config
required
string or null (Configuration repository)

Repository to clone the configuration files from

+
required
Array of objects (Files)

A list of files to add to the repository during initialization

+
required
object or null (Resources)

Responses

Request samples

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

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
Request Body schema: application/json
required
required
object or null (Resources)

Responses

Request samples

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

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
required
synchronize_code
required
boolean (Is code synchronized)

Synchronize code?

+
rebase
required
boolean (Is code rebased)

Synchronize code by rebasing instead of merging

+
synchronize_data
required
boolean (Is data synchronized)

Synchronize data?

+
synchronize_resources
required
boolean (Are resources synchronized)

Synchronize resources?

+

Responses

Request samples

Content type
application/json
{
  • "synchronize_code": true,
  • "rebase": true,
  • "synchronize_data": true,
  • "synchronize_resources": 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
required
object (Routing)

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
{
  • "id": "string",
  • "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
required
object (Routing)

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 backups, +get information about existing backups, delete existing backups or +restore a backup. +More information about backups can be found in our +documentation.

+

Create backup of environment

Trigger a new backup of an environment to be created. See the +Backups +section of the documentation for more information.

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

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 backup 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
[
  • {
    }
]

[Internal] Create an environment backup

Trigger an environment backup

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
required
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+

Responses

Request samples

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

Response samples

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

Get an environment backup'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
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "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,
  • "deployment": "string",
  • "restorable": true,
  • "automated": true
}

Delete an environment backup

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
required
environment_name
required
string or null (Environment name)
branch_from
required
string or null (Branch from)
restore_code
required
boolean (Is code or data restored)

Whether we should restore the code or only the data

+
restore_resources
required
boolean (Is resources restored)

Whether we should restore resources configuration from the backup

+
required
object or null (Resources)

Responses

Request samples

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

Response samples

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

Environment Type

Environment Types is the way Upsun manages access. We currently have 3 environment 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 environment will have a type, pointing to one of these 3 environment 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 environments in your project can be development or staging, but never production.
    • +
  • Dedicated Generation 2 environments can be set either to staging or production, but never development.
    • +
  • 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
{
  • "id": "string",
  • "attributes": {
    }
}

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 Environment Variables +section in our documentation for more information.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
required
name
required
string (Name)

Name of the variable

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
value
required
string (Value)

Value of the variable

+
is_json
boolean (Is JSON)

The variable is a JSON string

+
is_sensitive
boolean (Is Sensitive)

The variable is sensitive

+
visible_build
boolean (Is visible during build)

The variable is visible during build

+
visible_runtime
boolean (Visible at runtime)

The variable is visible at runtime

+
application_scope
Array of strings (Application Scope)

Applications that have access to this variable

+
is_enabled
boolean (Is enabled)

The variable is enabled on this environment

+
is_inheritable
boolean (Is inheritable)

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,
  • "application_scope": [
    ],
  • "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
{
  • "id": "string",
  • "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,
  • "application_scope": [
    ],
  • "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
required
name
string (Name)

Name of the variable

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
value
string (Value)

Value of the variable

+
is_json
boolean (Is JSON)

The variable is a JSON string

+
is_sensitive
boolean (Is Sensitive)

The variable is sensitive

+
visible_build
boolean (Is visible during build)

The variable is visible during build

+
visible_runtime
boolean (Visible at runtime)

The variable is visible at runtime

+
application_scope
Array of strings (Application Scope)

Applications that have access to this variable

+
is_enabled
boolean (Is enabled)

The variable is enabled on this environment

+
is_inheritable
boolean (Is inheritable)

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,
  • "application_scope": [
    ],
  • "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 .upsun/config.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 .upsun/config.yaml file.

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] 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 routes: section of the .upsun/config.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
required
One of
primary
boolean or null (Is primary)

This route is the primary route of the environment

+
id
string or null (Route Identifier)

Route Identifier

+
production_url
string or null (Production URL)

How this URL route would look on production environment

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
type
required
string (Route type)
Enum: "proxy" "redirect" "upstream"

Route type.

+
object (TLS settings)

TLS settings for the route.

+
to
required
string (Proxy destination)

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
{
  • "id": "string",
  • "primary": true,
  • "production_url": "string",
  • "attributes": {
    },
  • "type": "proxy",
  • "tls": {
    },
  • "to": "string"
}

[Internal] 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 .upsun/config.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
required
One of
primary
boolean or null (Is primary)

This route is the primary route of the environment

+
id
string or null (Route Identifier)

Route Identifier

+
production_url
string or null (Production URL)

How this URL route would look on production environment

+
object (Arbitrary attributes)

Arbitrary attributes attached to this resource

+
type
required
string (Route type)
Enum: "proxy" "redirect" "upstream"

Route type.

+
object (TLS settings)

TLS settings for the route.

+
to
required
string (Proxy destination)

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
}

[Internal] 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 routes: section of the .upsun/config.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 .upsun/config.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 .upsun/config.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
required
operation
required
string (Operation name)

The name of the operation to execute

+
required
object (Variables)

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 .upsun/config.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 .upsun/config.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
required
service
required
string (Application or worker name)

The name of the application or worker to run the operation on

+
operation
required
string (Operation name)

The name of the operation

+
parameters
required
Array of strings (Operation parameters)

The parameters to run the operation with

+

Responses

Request samples

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

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 file: .upsun/config.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
{
  • "id": "string",
  • "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": {
    }
}

[Internal] Update a deployment

Sizing scenarios for flexible resources projects. It is used to set sizes, disk and instance_count for the webapps, workers or services. +Change is triggerred by invoking PATCH request on the deployment object with id=next with changed values. +It is possible to set size of the service by changing its coresponding resource's property profile_size as a selector to services's containers profile. Disk can be also changed by updating service's disk property. +For webapps and workers it is possible to enable horizontal scaling by setting it's resource's instance_count property to start or stop additional instances of the service. Overtaken deployment object generates +new activity that does redeploy with new resources value for the services.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
deploymentId
required
string
Request Body schema: application/json
required
object (Services)
object (Web applications)
object (Workers)

Responses

Request samples

Content type
application/json
{
  • "services": {
    },
  • "webapps": {
    },
  • "workers": {
    }
}

Response samples

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

Autoscaling

Upsun provides native support for autoscaling, allowing your applications to automatically adjust based on resource usage. +This ensures that your apps remain responsive under load while helping you optimize costs. +You can configure thresholds for metrics such as CPU, RAM, and request latency.
Resources will automatically scale to meet demand. +Each container profile assigned to an application or service provides a specific combination of CPU and RAM, which you can select via the Upsun UI or CLI.

+

These endpoints manage autoscaling configurations that are tied to a +specific environment, and optionally to its child environments. +You can define scaling rules based on metrics like CPU, memory, or +request latency, and these rules will be applied at both build time +and runtime. For more information on configuring autoscaling for your +environments, see the Autoscaling section +of the documentation.

+

Retrieves Autoscaler settings

Retrieves Autoscaler settings

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

A string that uniquely identifies the project

+
environmentId
required
string

A string that uniquely identifies the project environment

+

Responses

Response samples

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

Updates Autoscaler settings

Updates Autoscaler settings

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

A string that uniquely identifies the project

+
environmentId
required
string

A string that uniquely identifies the project environment

+
Request Body schema: application/json

Settings to update

+
object or null (Services)

Each service for which autoscaling is configured is listed in the key

+

Responses

Request samples

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

Response samples

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

Modifies Autoscaler settings

Modifies Autoscaler settings

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

A string that uniquely identifies the project

+
environmentId
required
string

A string that uniquely identifies the project environment

+
Request Body schema: application/json

Settings to modify

+
object or null (Services)

Each service for which autoscaling is configured is listed in the key

+

Responses

Request samples

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

Response samples

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

[Internal] Sends an Autoscaler alert for processing

Sends an Autoscaler alert for processing

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

A string that uniquely identifies the project

+
environmentId
required
string

A string that uniquely identifies the project environment

+
Request Body schema: application/json

Alert to process

+
name
required
string (Name)

User friendly name for the alert

+
environment
string or null (Environment)

Environment for which the alert was received

+
service
required
string (Service)

Service for which the alert was received

+
resource
string or null (Resource)

Name of resource that triggered the alert

+
condition
required
string (Condition)

Comparison condition to use when evaluating the alert

+
threshold
required
number (Threshold)

Value that has to be crossed for the alert to be considered triggered

+
object or null

Number of seconds during which the condition was satisfied

+
value
required
number (Value)

Current value for the received alert

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "environment": "string",
  • "service": "string",
  • "resource": "string",
  • "condition": "string",
  • "threshold": 0,
  • "duration": {
    },
  • "value": 0
}

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 when the activity expires (expires_at).

+

There are 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.

    +
    • +
+

Expired activities are removed from the project activity log, except +the last 100 expired objects provided they are not of type environment.cron +or environment.backup.

+
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
{
  • "id": "string",
  • "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",
  • "commands": [
    ]
}

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
{
  • "id": "string",
  • "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",
  • "commands": [
    ]
}

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
}

[Internal] Get integration activities

Get the activity logs for the integration.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Get an integration activity log entry

Retrieve a single integration activity entry as specified by an +id returned by the Get integration activities list endpoint

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string
activityId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "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",
  • "commands": [
    ]
}

[Internal] Cancel an integration activity

Cancel a single activity as specified by an id returned by the +Get integration activity log.

+

Please note that not all activities are cancelable.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
integrationId
required
string
activityId
required
string

Responses

Response samples

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

Project Invitations

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
role
string
Default: null
Enum: "admin" "viewer"

The role the invitee should be given on the project.

+
email
required
string <email>

The email address of the invitee.

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

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 (StringFilter)

Allows filtering by 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
required
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
required
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": {
    }
}

Team Access

List team 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

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: granted_at, updated_at.

+

Responses

Response samples

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

Grant team access to a project

Grants one or more team access to a specific project.

+
Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

+
Request Body schema: application/json
required
Array
team_id
required
string

ID of the team.

+

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Get team access for a project

Retrieves the team's permissions for the current project.

+
Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

+
team_id
required
string

The ID of the team.

+

Responses

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "project_title": "string",
  • "granted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Remove team access for a project

Removes the team from the current project.

+
Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

+
team_id
required
string

The ID of the team.

+

Responses

Response samples

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

List project access for a team

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

+
Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

+
query Parameters
page[size]
integer [ 1 .. 200 ]
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: project_title, granted_at, updated_at.

+

Responses

Response samples

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

Grant project access to a team

Adds the team to one or more specified projects.

+
Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

+
Request Body schema: application/json
required
Array
project_id
required
string

ID of the project.

+

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 team

Retrieves the team's permissions for the current project.

+
Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

+
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "team_id": "string",
  • "organization_id": "string",
  • "project_id": "string",
  • "project_title": "string",
  • "granted_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Remove project access for a team

Removes the team from the current project.

+
Authorizations:
OAuth2
path Parameters
team_id
required
string

The ID of the team.

+
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 Access

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

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

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

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

Catalogs

[Internal] Create catalog

Creates a new catalog.

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

name of the catalog.

+
type_name
string

The type of the catalog.

+
type_value
string

The type value of the catalog.

+
object (CatalogTemplate)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type_name": "string",
  • "type_value": "string",
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "vendor": "string",
  • "name": "string",
  • "type_name": "string",
  • "type_value": "string",
  • "template": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] List catalogs

Retrieves a list of all catalogs

+
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Get catalog

Retrieves the specified catalog.

+
Authorizations:
OAuth2
path Parameters
id
required
string

The id of the catalog.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "vendor": "string",
  • "name": "string",
  • "type_name": "string",
  • "type_value": "string",
  • "template": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Update catalog

Updates the specified catalog.

+
Authorizations:
OAuth2
path Parameters
id
required
string

The id of the catalog.

+
Request Body schema: application/json
required
name
string

name of the catalog.

+
type_name
string

The type of the catalog.

+
type_value
string

The type value of the catalog.

+
object (CatalogTemplate)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type_name": "string",
  • "type_value": "string",
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "vendor": "string",
  • "name": "string",
  • "type_name": "string",
  • "type_value": "string",
  • "template": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Delete catalog

Deletes the specified catalog.

+
Authorizations:
OAuth2
path Parameters
id
required
string

The id of the catalog.

+

Responses

Response samples

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

[Internal] Get catalog for an organization

Retrieves the catalog for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Wizards

[Internal] Create wizard

Creates a new wizard.

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

Name of the template.

+
Array of objects or null (WizardSteps)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ]
}

Response samples

Content type
application/json
{
  • "vendor": "string",
  • "name": "string",
  • "steps": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] List wizards

Retrieves a list of all wizards.

+
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Get wizard

Retrieves a wizard for the specified template.

+
Authorizations:
OAuth2
path Parameters
name
required
string

The name of the template.

+

Responses

Response samples

Content type
application/json
{
  • "vendor": "string",
  • "name": "string",
  • "steps": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Update wizard

Updates the wizard for the specified template.

+
Authorizations:
OAuth2
path Parameters
name
required
string

The name of the template.

+
Request Body schema: application/json
required
Array
id
required
string

ID of the wizard step.

+
label
required
string

Label of the wizard step.

+
title
required
string

Title of the wizard step.

+
required
required
boolean

Mentions if the step is required.

+
bodyText
required
string

Body text of the wizard step.

+
Array of objects or null (StepCopyCode)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "vendor": "string",
  • "name": "string",
  • "steps": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Delete wizard

Deletes the wizard for the specified template.

+
Authorizations:
OAuth2
path Parameters
name
required
string

The name of the template.

+

Responses

Response samples

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

[Internal] Get wizard for an organization

Retrieves a wizard for the specified organization and template.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
name
required
string

The name of the template.

+

Responses

Response samples

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

Project Options

[Internal] Create project option

Creates a new project option.

+
Authorizations:
OAuth2
Request Body schema: application/json
required
billing
object
defaults
object
enforced
object
initialize
object
plans
object (OptionsPlans)
regions
object (OptionsRegions)
sellables
object (Sellables)
settings
object (Settings)
version
number

Version of the project options.

+
type
string (OptionsType)
Enum: "oem" "orgtype" "plan" "tier" "organization" "trial"

The type of the project options.

+
name
string (OptionsName)

The name of the project options.

+

Responses

Request samples

Content type
application/json
{
  • "billing": { },
  • "defaults": { },
  • "enforced": { },
  • "initialize": { },
  • "plans": { },
  • "regions": { },
  • "sellables": { },
  • "settings": { },
  • "version": 0,
  • "type": "oem",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "defaults": {
    },
  • "enforced": {
    },
  • "regions": [
    ],
  • "plans": [
    ],
  • "billing": { }
}

[Internal] List project options

Retrieves a list of all defined project options.

+
Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by type using one or more operators.

+
object (StringFilter)

Allows filtering by name 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: id, name, created_at, updated_at.

+

Responses

Response samples

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

[Internal] Get project option

Retrieves the specified project option.

+
Authorizations:
OAuth2
path Parameters
options_id
required
string

The ID of the project options.

+

Responses

Response samples

Content type
application/json
{
  • "defaults": {
    },
  • "enforced": {
    },
  • "regions": [
    ],
  • "plans": [
    ],
  • "billing": { }
}

[Internal] Update project option

Updates the specified project option.

+
Authorizations:
OAuth2
path Parameters
options_id
required
string

The ID of the project options.

+
Request Body schema: application/json
required
billing
object
defaults
object
enforced
object
initialize
object
plans
object (OptionsPlans)
regions
object (OptionsRegions)
sellables
object (Sellables)
settings
object (Settings)
version
number

Version of the project options.

+

Responses

Request samples

Content type
application/json
{
  • "billing": { },
  • "defaults": { },
  • "enforced": { },
  • "initialize": { },
  • "plans": { },
  • "regions": { },
  • "sellables": { },
  • "settings": { },
  • "version": 0
}

Response samples

Content type
application/json
{
  • "defaults": {
    },
  • "enforced": {
    },
  • "regions": [
    ],
  • "plans": [
    ],
  • "billing": { }
}

[Internal] Delete project option

Deletes the specified project option.

+
Authorizations:
OAuth2
path Parameters
options_id
required
string

The ID of the project options.

+

Responses

Response samples

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

[Internal] List project options for an organization

Retrieves a list of project options for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
query Parameters
plan
string

Specifies the plan.

+
template
string

Specifies the template URL.

+
organization
string

Specifies the organization option name.

+

Responses

Response samples

Content type
application/json
{
  • "billing": { },
  • "defaults": { },
  • "enforced": { },
  • "initialize": { },
  • "plans": [
    ],
  • "regions": [
    ],
  • "plan_titles": { },
  • "sellables": { },
  • "features": { }
}

[Internal] Update project options for an organization

Update project options for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
Request Body schema: application/json
required
options
required
Array of strings

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "fixed",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "namespace": "string",
  • "name": "string",
  • "label": "string",
  • "country": "st",
  • "capabilities": [
    ],
  • "vendor": "string",
  • "netsuite_id": "string",
  • "billing_account_id": "string",
  • "billing_legacy": true,
  • "security_contact": "user@example.com",
  • "notes": "string",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

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",
  • "mfa_on_creation": true,
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_used_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",
  • "mfa_on_creation": true,
  • "token": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_used_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",
  • "provider_type": "string",
  • "is_mandatory": true,
  • "subject": "string",
  • "email_address": "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"
}

Grants

[Internal] List grants

List permissions granted to users or teams.

+
Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by principal_id using one or more operators.

+
object (StringFilter)

Allows filtering by principal_type (user or team) using one or more operators.

+
object (StringFilter)

Allows filtering by resource_id using one or more operators.

+
object (StringFilter)

Allows filtering by resource_type (project or organization) using one or more operators.

+
object (StringFilter)

Allows filtering by organization_id using one or more operators.

+
object (StringFilter)

Allows filtering by permissions using one or more operators.

+
page[size]
integer [ 1 .. 1000 ]
Default: null

Determines the number of items to show.

+
page[after]
string

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

+
page[before]
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": {
    }
}

[Internal] Manage grants

Allows creating, updating or deleting multiple grants in a single request.

+
Authorizations:
OAuth2
Request Body schema: application/json
required
Array of objects

The grant objects to create.

+
Array of objects

The grant objects whose permissions will be updated.

+
Array of objects

The grant objects to be merged. +If matching grants exist, their permissions will be merged. +If not, new grants will be created.

+
Array of objects

Fields used to match and delete grants or their permissions. +The caller can specify just the principal_id/principal_type, resource_id/resource_type, and/or an organization_id. +Additionally, permissions can be specified in case they are being deleted rather than entire grants.

+

Responses

Request samples

Content type
application/json
{
  • "create": [
    ],
  • "update": [
    ],
  • "merge": [
    ],
  • "clear": [
    ]
}

Response samples

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

[Internal] List extended access of a project

List extended access to the given project, having access of individual users and users from team.

+
Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

+
query Parameters
object (StringFilter)

Allows filtering by user_id using one or more operators.

+
object

Allows filtering by access_type using one or more operators.

+

Responses

Response samples

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

List extended access of a user

List extended access of the given user, which includes both individual and team access to project and organization.

+
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 resource_type (project or organization) using one or more operators.

+
object (StringFilter)

Allows filtering by organization_id using one or more operators.

+
object (StringFilter)

Allows filtering by permissions using one or more operators.

+

Responses

Response samples

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

[Internal] Get user access document

Get the user's access document. Intended only for fallback checks, e.g. for SSH access.

+
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
{
  • "access": { },
  • "access_id": "string",
  • "deactivated": true
}

[Internal] List organization user counts per access level.

List number of users per access level (admin or viewer) within the organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

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

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": [
    ]
}

Get organization MFA settings

Retrieves MFA settings 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Enable organization MFA enforcement

Enables MFA enforcement for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Disable organization MFA enforcement

Disables MFA enforcement for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Send MFA reminders to organization members

Sends a reminder about setting up MFA to the specified organization members.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
user_ids
Array of strings <uuid> [ items <uuid > ]

The organization members.

+

Responses

Request samples

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

Response samples

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

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

[Internal] List updated users

Retrieves a list of users updated since the specified date.

+
Authorizations:
OAuth2Admin
query Parameters
updated_since
string <date-time>
Example: updated_since=2014-04-01T00:00:00Z
after
string

The pagination cursor.

+
count
integer [ 1 .. 1000 ]
Default: null

The number of users to retrieve.

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a user

Back-channel registration for user import.

+
Authorizations:
OAuth2Admin
Request Body schema: application/json
username
required
string
email_address
required
string <email>
first_name
string
last_name
string
object

Login credentials for the user being created

+

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email_address": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "credentials": {
    }
}

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

[Internal] Delete a user

Deletes the specified user.

+
Authorizations:
OAuth2Admin
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"
}

[Internal] Reactivate a user

Reactivates the specified user.

+
Authorizations:
OAuth2Admin
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"
}

[Internal] Deactivate a user

Deactivates the specified user.

+
Authorizations:
OAuth2Admin
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"
}

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

[Internal] Get identity analysis of a user

Retrieves the identity analysis of 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
{
  • "normalized_email_domain": "string",
  • "normalized_email_count": 0,
  • "normalized_email_deactivated_count": 0,
  • "phone_number_country": "string",
  • "phone_number_hash": "string",
  • "phone_number_count": 0
}

[Internal] Get configuration rules for email

Returns configuration rules for a specific email address or domain.

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

The email address or domain to check against internal rules.

+

Responses

Response samples

Content type
application/json
{
  • "blocked": true,
  • "mandatory_sso_provider": "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",
  • "status": "active",
  • "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",
  • "agency_partner_tier": "registered",
  • "account_restricted": true,
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "current_trial": {
    },
  • "payment_methods": [
    ],
  • "invoiced": true,
  • "tax_exempt": true,
  • "extra_regions": [
    ]
}

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",
  • "status": "active",
  • "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",
  • "agency_partner_tier": "registered",
  • "account_restricted": true,
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "current_trial": {
    },
  • "payment_methods": [
    ],
  • "invoiced": true,
  • "tax_exempt": true,
  • "extra_regions": [
    ]
}

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

+
Request Body schema: multipart/form-data
required
file
string <binary>

The image file to upload.

+

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

[Internal] List a user's SSH keys

Retrieve all SSH keys associated with a single user, as specified by the user's UUID.

+
Authorizations:
OAuth2
path Parameters
uuid
required
string <uuid>

The UUID of the owner.

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Organization Management

[Internal] Retrieves a list of all prepaid (FRF) organizations and their prepayment information

Authorizations:
OAuth2

Responses

Response samples

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

Estimate total spend

Estimates the total spend 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "total": "string",
  • "sub_total": "string",
  • "vouchers": "string",
  • "user_licenses": {
    },
  • "user_management": "string",
  • "support_level": "string",
  • "subscriptions": {
    }
}

[Internal] List scheduled dunning actions

Retrieves a list of all scheduled dunning actions for an organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Get billing alert configuration

Retrieves billing alert configuration 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "active": true,
  • "alerts_sent": 0,
  • "last_alert_at": "string",
  • "updated_at": "string",
  • "config": {
    }
}

Update billing alert configuration

Updates billing alert configuration 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
active
boolean

Whether the billing alert should be active or not.

+
object

The configuration for billing alerts.

+

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "active": true,
  • "alerts_sent": 0,
  • "last_alert_at": "string",
  • "updated_at": "string",
  • "config": {
    }
}

[Internal] List banners

Retrieves a list of banners 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Get organization prepayment information

Retrieves prepayment information for the specified organization, if applicable.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "prepayment": {
    },
  • "_links": {
    }
}

List organization prepayment transactions

Retrieves a list of prepayment transactions for the specified organization, if applicable.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

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

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.

+

[Internal] List project caps

Retrieve all caps for a project.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+

Responses

Response samples

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

[Internal] List caps of type

List all caps of a particular type for a particular project.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
capsType
required
string
Value: "env-type"

The type of the caps

+

Responses

Response samples

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

[Internal] Set caps

Set new caps of a type for a project.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
capsType
required
string
Value: "env-type"

The type of the caps

+
Request Body schema: application/json
resource_preset
string

The resource preset for the project caps.

+
name
any
Enum: "development" "staging" "production"

The environment type name.

+
cpu
number

The cpu value.

+
memory
integer

The memory value.

+
storage
integer

The storage value.

+
environments
integer

The environments value.

+

Responses

Request samples

Content type
application/json
{
  • "resource_preset": "string",
  • "name": "development",
  • "cpu": 0,
  • "memory": 0,
  • "storage": 0,
  • "environments": 0
}

Response samples

Content type
application/json
{
  • "envName": "string",
  • "capsType": "string",
  • "resource_preset": "string",
  • "storage": 0,
  • "environments": 0,
  • "resources": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] List caps of type for env

For a particular project, retrieve a list of caps of a type for a single environment.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
capsType
required
string
Value: "env-type"

The type of the caps

+
envName
required
string
Enum: "development" "staging" "production"

The name of the environment type

+

Responses

Response samples

Content type
application/json
{
  • "envName": "string",
  • "capsType": "string",
  • "resource_preset": "string",
  • "storage": 0,
  • "environments": 0,
  • "resources": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] Delete caps

Delete all caps of a type for a project.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
capsType
required
string
Value: "env-type"

The type of the caps

+
envName
required
string
Enum: "development" "staging" "production"

The name of the environment type

+

Responses

[Internal] Update caps

Update a project environment caps of a particular type.

+
Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
capsType
required
string
Value: "env-type"

The type of the caps

+
envName
required
string
Enum: "development" "staging" "production"

The name of the environment type

+
Request Body schema: application/json
resource_preset
string

The resource preset.

+
cpu
number

The cpu value.

+
memory
integer

The memory value.

+
storage
integer

The storage value.

+
environments
integer

The maximum number of environments.

+

Responses

Request samples

Content type
application/json
{
  • "resource_preset": "string",
  • "cpu": 0,
  • "memory": 0,
  • "storage": 0,
  • "environments": 0
}

Response samples

Content type
application/json
{
  • "envName": "string",
  • "capsType": "string",
  • "resource_preset": "string",
  • "storage": 0,
  • "environments": 0,
  • "resources": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

[Internal] List all caps size

List the caps associated with the various plan sizes

+
Authorizations:
OAuth2

Responses

Response samples

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

[Internal] Start a new subscription without provisioning the project

Authorizations:
OAuth2
Request Body schema: application/json
region
string

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

+
project_id
string

The project id.

+
organization_id
string

The organization id.

+
plan
string
Default: null
Enum: "development" "standard" "medium" "large" "xlarge" "2xlarge"

The plan type of the subscription.

+

Responses

Request samples

Content type
application/json
{
  • "region": "string",
  • "project_id": "string",
  • "organization_id": "string",
  • "plan": "development"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

[Internal] Suspend a subscription

Authorizations:
OAuth2
path Parameters
subscriptionId
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",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

[Internal] Reactivate a subscription

Authorizations:
OAuth2
path Parameters
subscriptionId
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",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

[Internal] Change the owner of a subscription

Authorizations:
OAuth2
path Parameters
subscriptionId
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",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

[Internal] Calculate conversion cost for license from a fixed to flexible plan

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
query Parameters
format
string
Default: null
Enum: "formatted" "complex"

The format mode of the estimation.

+
include_org_costs
string
Default: null
Enum: "0" "1"

Whether to include an estimate of organization costs for a conversion.

+

Responses

Response samples

Content type
application/json
{
  • "plan": "string",
  • "resources_total": "string",
  • "total": "string"
}

Checks if the user is able to update a project.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
query Parameters
plan
string
Enum: "development" "standard" "medium" "large" "xlarge" "2xlarge"

The plan type of the subscription.

+
environments
integer
Default: null

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

+
storage
integer
Default: null

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

+
user_licenses
integer

The number of user licenses.

+
ignore_admin
boolean

[Internal] Ignore admin privileges to simulate the response a customer may get

+

Responses

Response samples

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

[Internal] Checks if a project is allowed to be transferred to a specific organization.

Authorizations:
OAuth2
path Parameters
subscriptionId
required
string

The ID of the subscription

+
query Parameters
target_organization
required
string

[Internal] The target organization ID desired to own the project after transfer.

+

Responses

Response samples

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

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

[Internal] Get the environment caps

Retrieves the environment caps of a project.

+
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/json
{
  • "type": "string",
  • "name": "string",
  • "cpu": 0,
  • "memory": "string",
  • "storage": 0,
  • "environments": 0
}

[Internal] Create a new environment cap

Creates a new environment cap for the given project.

+
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
required
type
required
string
Value: "env-type"

The type of caps (only env-type is supported at the moment).

+
name
required
string

The name of the caps.

+
storage
integer

The total storage available to each environment, in MiB.

+
environments
integer

The maximum number of environments allowed for this type.

+
memory
number

The total memory available to each environment, in GiB.

+
cpu
number

The total cpu available to each environment.

+
resource_preset
string (ResourcePreset)
Enum: "Small" "Standard" "Medium" "Large" "XL" "2XL" "4XL"

The resource preset.

+

Responses

Request samples

Content type
application/json
{
  • "type": "env-type",
  • "name": "string",
  • "storage": 0,
  • "environments": 0,
  • "memory": 0,
  • "cpu": 0,
  • "resource_preset": "Small"
}

Response samples

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

[Internal] Get an environment type cap

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
subscription_id
required
string

The ID of the subscription.

+
caps_type
required
string

[Internal] The type of the environment cap.

+
env_type
required
string

[Internal] The environment type name.

+

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "name": "string",
  • "cpu": 0,
  • "memory": "string",
  • "storage": 0,
  • "environments": 0
}

[Internal] Update an environment cap

Updates an environment cap for the given project.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
subscription_id
required
string

The ID of the subscription.

+
caps_type
required
string

[Internal] The type of the environment cap.

+
env_type
required
string

[Internal] The environment type name.

+
Request Body schema: application/json
required
type
required
string
Value: "env-type"

The type of caps (only env-type is supported at the moment).

+
name
required
string

The name of the caps.

+
storage
integer

The total storage available to each environment, in MiB.

+
environments
integer

The maximum number of environments allowed for this type.

+
memory
number

The total memory available to each environment, in GiB.

+
cpu
number

The total cpu available to each environment.

+
resource_preset
string (ResourcePreset)
Enum: "Small" "Standard" "Medium" "Large" "XL" "2XL" "4XL"

The resource preset.

+

Responses

Request samples

Content type
application/json
{
  • "type": "env-type",
  • "name": "string",
  • "storage": 0,
  • "environments": 0,
  • "memory": 0,
  • "cpu": 0,
  • "resource_preset": "Small"
}

Response samples

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

[Internal] Delete and environment cap

Deletes the specified environment cap.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
subscription_id
required
string

The ID of the subscription.

+
caps_type
required
string

[Internal] The type of the environment cap.

+
env_type
required
string

[Internal] The environment type name.

+

Responses

Response samples

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

[Internal] Get all the environment caps of a project

Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
subscription_id
required
string

The ID of the subscription.

+
caps_type
required
string

[Internal] The type of the environment cap.

+

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "name": "string",
  • "cpu": 0,
  • "memory": "string",
  • "storage": 0,
  • "environments": 0
}

Get current usage for 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
usage_groups
string

A list of usage groups to retrieve current usage for.

+
include_not_charged
boolean

Whether to include not charged usage groups.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "cpu_app": {
    },
  • "storage_app_services": {
    },
  • "memory_app": {
    },
  • "cpu_services": {
    },
  • "memory_services": {
    },
  • "backup_storage": {
    },
  • "build_cpu": {
    },
  • "build_memory": {
    },
  • "egress_bandwidth": {
    },
  • "ingress_requests": {
    },
  • "logs_fwd_content_size": {
    },
  • "fastly_bandwidth": {
    },
  • "fastly_requests": {
    }
}

List addons for 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "available": {
    },
  • "current": {
    },
  • "upgrades_available": {
    }
}

Get usage alerts

Retrieves current and available usage alerts.

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "current": [
    ],
  • "available": [
    ]
}

Update usage alerts.

Updates usage alerts for a subscription.

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
Array of objects

The list of alerts to update.

+

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "current": [
    ],
  • "available": [
    ]
}

List subscriptions

Retrieves subscriptions for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

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

The status of the subscription.

+
filter[id]
string

Machine name of the region.

+
object (StringFilter)

Allows filtering by project_id using one or more operators.

+
object (StringFilter)

Allows filtering by project_title using one or more operators.

+
object (StringFilter)

Allows filtering by region 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
Example: sort=-updated_at

Allows sorting by a single field.
+Use a dash ("-") to sort descending.
+Supported fields: region, project_title, type, plan, status, created_at, updated_at.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
required
plan
string (ProjectPlan)

The project plan.

+
project_region
required
string

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

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

+
options_custom
object (ProjectOptionsCustom)

[Internal] Customizations at creation time integrated into project options.

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

+
project_notes
string

[Internal] The CSE notes for this project.

+
support_tier
string (SupportTier)

[Internal] The support tier for this subscription.

+
enterprise_tag
string

[Internal] The enterprise application identifier associated with this project.

+
agency_site
boolean (AgencySite)

[Internal] Whether the project is marked as as agency site.

+
hipaa
string (HIPAA)

[Internal] The HIPAA option.

+
edgee_org_id
string (EdgeeOrgID)

[Internal] The organization id of the edgee service.

+
edgee_project_id
string (EdgeeProjectID)

[Internal] The project id of the edgee service.

+

Responses

Request samples

Content type
application/json
{
  • "plan": "string",
  • "project_region": "string",
  • "project_title": "string",
  • "options_url": "string",
  • "options_custom": { },
  • "default_branch": "string",
  • "environments": 0,
  • "storage": 0,
  • "project_notes": "string",
  • "support_tier": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

Get subscription

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
project_title
string (ProjectTitle)

The title of the project.

+
plan
string (ProjectPlan)

The project plan.

+
timezone
string (ProjectTimeZone)

Timezone of the project.

+
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 option.

+
blackfire
string

The Blackfire integration option.

+
continuous_profiling
string

The Blackfire continuous profiling option.

+
project_support_level
string

The project uptime option.

+
project_notes
string

[Internal] The CSE notes for this project.

+
support_tier
string (SupportTier)

[Internal] The support tier for this subscription.

+
enterprise_tag
string

[Internal] The enterprise application identifier associated with this project.

+
agency_site
boolean

[Internal] Whether the project is marked as as agency site.

+
hipaa
string

[Internal] The HIPAA option.

+
edgee_org_id
string (EdgeeOrgID)

[Internal] The organization id of the edgee service.

+
edgee_project_id
string (EdgeeProjectID)

[Internal] The project id of the edgee service.

+

Responses

Request samples

Content type
application/json
{
  • "project_title": "string",
  • "plan": "string",
  • "timezone": "string",
  • "environments": 0,
  • "storage": 0,
  • "big_dev": "string",
  • "big_dev_service": "string",
  • "backups": "string",
  • "observability_suite": "string",
  • "blackfire": "string",
  • "continuous_profiling": "string",
  • "project_support_level": "string",
  • "project_notes": "string",
  • "support_tier": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "hipaa": "string",
  • "edgee_org_id": "string",
  • "edgee_project_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "requested",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_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_notes": "string",
  • "project_ui": "string",
  • "project_options": {
    },
  • "options_url": "string",
  • "enterprise_tag": "string",
  • "agency_site": true,
  • "invoiced": true,
  • "support_tier": "string",
  • "hipaa": true,
  • "is_trial_plan": true,
  • "services": [
    ],
  • "locked": true,
  • "green": true
}

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

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.

+

[Internal] Enqueues a refresh for provided order

Enqueues the order to refresh its line_items

+
Authorizations:
OAuth2
path Parameters
orderId
required
string

The ID of the order

+

Responses

Response samples

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

Download an invoice.

Authorizations:
OAuth2
query Parameters
token
required
string

JWT for invoice.

+

Responses

[Internal] List payment transactions

Authorizations:
OAuth2
query Parameters
page
integer <int32>

Page to be displayed. Defaults to 1.

+
all
string

[Internal] Add this parameter with whichever value to display all projects, otherwise, only projects owned by current user will be displayed (admins only).

+

Responses

Response samples

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

[Internal] Get payment transaction

Authorizations:
OAuth2
path Parameters
id
required
string

The ID of the transaction

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner": "534359f7-5407-4b19-ba92-c71c370022a5",
  • "order_id": 0,
  • "payment_method": "string",
  • "message": "string",
  • "status": "success",
  • "remote_id": "string",
  • "remote_status": "paid",
  • "amount": 0,
  • "currency": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

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.

+
mode
string
Value: "details"

The output mode.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
query Parameters
mode
string
Value: "details"

The output mode.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Create confirmation credentials for for 3D-Secure

Creates confirmation credentials for payments that require online authorization

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

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.

+
all
string

[Internal] Add this parameter with whichever value to display all projects, otherwise, only projects owned by current user will be displayed (admins only).

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.1,
  • "address": {
    },
  • "notes": "string",
  • "invoice_pdf": {
    }
}

Discounts

Get an organization discount

Authorizations:
OAuth2
path Parameters
id
required
string

The ID of the organization discount

+

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "organization_id": "string",
  • "type": "allowance",
  • "type_label": "string",
  • "status": "inactive",
  • "commitment": {
    },
  • "total_months": 0,
  • "discount": {
    },
  • "config": { },
  • "start_at": "2019-08-24T14:15:22Z",
  • "end_at": "2019-08-24T14:15:22Z"
}

[Internal] Update the configuration of organization discount.

Authorizations:
OAuth2
path Parameters
id
required
string

The ID of the organization discount

+
Request Body schema: application/json
status
string
Value: "deactivated"

Update discount status.

+
object

The configuration of the discount (if applicable)

+

Responses

Request samples

Content type
application/json
{
  • "status": "deactivated",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "organization_id": "string",
  • "type": "allowance",
  • "type_label": "string",
  • "status": "inactive",
  • "commitment": {
    },
  • "total_months": 0,
  • "discount": {
    },
  • "config": { },
  • "start_at": "2019-08-24T14:15:22Z",
  • "end_at": "2019-08-24T14:15:22Z"
}

Get the value of the First Project Incentive discount

Authorizations:
OAuth2

Responses

Response samples

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

List organization discounts

Retrieves all applicable discounts granted to 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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Vouchers

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

+

[Internal] Administrative all-vouchers listing.

Supplmenental voucher API for handling administrative list requests.

+
Authorizations:
OAuth2

Responses

Response samples

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

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+
Request Body schema: application/json
required
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"
}

Pricebooks

[Internal] List pricebooks

Retrieves a list of pricebooks for all organizations. Unless the organization is using the default pricebook, each pricebook will only list overridden prices (custom to the organization, inherited from the tier, or a combination).

+
Authorizations:
OAuth2
query Parameters
filter[pricebook_source]
string
Enum: "organization" "tier" "default"

The source of the pricebook (organization, tier, default).

+

Responses

Response samples

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

[Internal] Show pricebook for an organization

Retrieves an organization's pricebook. Unless the organization is using the default pricebook, the pricebook will only list overridden prices (custom to the organization, inherited from the tier, or a combination).

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ULID of the organization

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "pricebook_source": "string",
  • "currency": "string",
  • "products": { }
}

[Internal] Replace a pricebook

Replaces an entire pricebook for an organization, or adds one if missing.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ULID of the organization

+
Request Body schema: application/json
products
required
object

The new pricebook (a map of {sku: price}). Prices should be specified as decimals.

+

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "pricebook_source": "string",
  • "currency": "string",
  • "products": { }
}

[Internal] Delete a pricebook

Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ULID of the organization

+

Responses

[Internal] Update a pricebook

Updates prices for one or more products of an organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string

The ULID of the organization

+
Request Body schema: application/json
object

Items (a map of {sku: price}) to update in the pricebook. Prices should be specified as decimals.

+

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "string",
  • "pricebook_source": "string",
  • "currency": "string",
  • "products": { }
}

[Internal] Show pricebook for a tier

Authorizations:
OAuth2
path Parameters
tier_id
required
string
Enum: "elite" "enterprise" "new" "premier" "pro" "trial"

The machine name for a tier

+
currency
required
string
Enum: "AUD" "CAD" "EUR" "GBP" "USD"

Currency abbreviation.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "pricebook_source": "string",
  • "currency": "string",
  • "products": { }
}

[Internal] Show default pricebook

Authorizations:
OAuth2
path Parameters
currency
required
string
Enum: "AUD" "CAD" "EUR" "GBP" "USD"

Currency abbreviation.

+

Responses

Response samples

Content type
application/json
{
  • "pricebook_source": "string",
  • "currency": "string",
  • "products": { }
}

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

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

Profiles

[Internal] Delete organization or user profile

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

+

Responses

[Internal] Get profile status

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

+

Responses

Response samples

Content type
application/json
{
  • "total_unpaid": true,
  • "owns_projects": true,
  • "can_delete": true
}

[Internal] Get profile billing report

Authorizations:
OAuth2
path Parameters
userId
required
string

The UUID of the user

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

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.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

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

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

+

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "active",
  • "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",
  • "agency_partner_tier": "registered",
  • "account_restricted": true,
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "current_trial": {
    },
  • "payment_methods": [
    ],
  • "invoiced": true,
  • "tax_exempt": true,
  • "extra_regions": [
    ]
}

Update profile

Updates the profile for the specified organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+
header Parameters
X-Platform-Vendor
string

[Internal] The vendor.

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

+
account_tier
string

[Internal] The account tier.

+
agency_partner_tier
string

[Internal] The agency partner tier.

+
salesperson
string <uuid>

[Internal] The user ID of a Platform.sh sales representative.

+
internal_contact
Array of strings <uuid> [ items <uuid > ]

[Internal] The user IDs of internal contacts.

+

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",
  • "account_tier": "string",
  • "agency_partner_tier": "string",
  • "salesperson": "c83195e8-c859-4584-b73b-0617409753e8",
  • "internal_contact": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "active",
  • "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",
  • "agency_partner_tier": "registered",
  • "account_restricted": true,
  • "marketing": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "billing_contact": "user@example.com",
  • "current_trial": {
    },
  • "payment_methods": [
    ],
  • "invoiced": true,
  • "tax_exempt": true,
  • "extra_regions": [
    ]
}

Project Discovery

[Internal] Locate project

Retrieves the region and organization for the specified project.

+
Authorizations:
OAuth2
path Parameters
project_id
required
string

The ID of the project.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "region": "string",
  • "endpoint": "string",
  • "subscription_id": "string",
  • "organization_id": "string"
}

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

List referenced projects

Retrieves a list of projects 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:projects:0.

+
Authorizations:
OAuth2
query Parameters
in
required
string

The list of comma-separated project 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": {
    }
}

List referenced regions

Retrieves a list of regions 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:regions:0.

+
Authorizations:
OAuth2
query Parameters
in
required
string

The list of comma-separated region 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": {
    }
}

Regions

List regions

Retrieves a list of available regions.

+
Authorizations:
OAuth2
query Parameters
object (StringFilter)

Allows filtering by available using one or more operators.

+
object (StringFilter)

Allows filtering by private using one or more operators.

+
object (StringFilter)

Allows filtering by zone 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: id, created_at, updated_at.

+

Responses

Response samples

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

[Internal] Create region

Creates a new region.

+
Authorizations:
OAuth2
Request Body schema: application/json
required
id
required
string (RegionID)

The machine name of the region where the project is located.

+
label
required
string (RegionLabel)

The human-readable name of the region.

+
zone
string (RegionZone)

The geographical zone of the region.

+
selection_label
required
string (RegionSelectionLabel)

The label to display when choosing between regions for new projects.

+
project_label
required
string (RegionProjectLabel)

The label to display on existing projects.

+
timezone
required
string (RegionTimezone)

Default timezone of the region.

+
available
required
boolean (RegionAvailable)

Indicator whether or not this region is selectable during the checkout. Not available regions will never show up during checkout.

+
private
required
boolean (RegionPrivate)

Indicator whether or not this platform is for private use only.

+
endpoint
required
string (RegionEndpoint)

Link to the region API endpoint.

+
code
required
string (RegionCode)

The code of the region

+
provider
object (RegionProvider)

Information about the region provider.

+
datacenter
required
object (RegionDataCenter)

Information about the region provider data center.

+
envimpact
object (RegionEnvImpact)

Information about the region provider's environmental impact.

+
compliance
object (RegionCompliance)

Information about the region's compliance.

+

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "zone": "string",
  • "selection_label": "string",
  • "project_label": "string",
  • "timezone": "string",
  • "available": true,
  • "private": true,
  • "endpoint": "string",
  • "code": "string",
  • "provider": { },
  • "datacenter": { },
  • "envimpact": { },
  • "compliance": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "zone": "string",
  • "selection_label": "string",
  • "project_label": "string",
  • "timezone": "string",
  • "available": true,
  • "private": true,
  • "endpoint": "string",
  • "provider": {
    },
  • "datacenter": {
    },
  • "environmental_impact": {
    }
}

Get region

Retrieves the specified region.

+
Authorizations:
OAuth2
path Parameters
region_id
required
string

The ID of the region.

+

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "zone": "string",
  • "selection_label": "string",
  • "project_label": "string",
  • "timezone": "string",
  • "available": true,
  • "private": true,
  • "endpoint": "string",
  • "provider": {
    },
  • "datacenter": {
    },
  • "environmental_impact": {
    }
}

[Internal] Update region

Updates the specified region.

+
Authorizations:
OAuth2
path Parameters
region_id
required
string

The ID of the region.

+
Request Body schema: application/json
available
boolean (RegionAvailable)

Indicator whether or not this region is selectable during the checkout. Not available regions will never show up during checkout.

+
private
boolean (RegionPrivate)

Indicator whether or not this platform is for private use only.

+
label
string (RegionLabel)

The human-readable name of the region.

+
hipaa
boolean (RegionHipaa)

Indicator whether or not this region is HIPAA compliant.

+

Responses

Request samples

Content type
application/json
{
  • "available": true,
  • "private": true,
  • "label": "string",
  • "hipaa": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "zone": "string",
  • "selection_label": "string",
  • "project_label": "string",
  • "timezone": "string",
  • "available": true,
  • "private": true,
  • "endpoint": "string",
  • "provider": {
    },
  • "datacenter": {
    },
  • "environmental_impact": {
    }
}

[Internal] Delete region

Deletes the specified region.

+
Authorizations:
OAuth2
path Parameters
region_id
required
string

The ID of the region.

+

Responses

Response samples

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

Data Centers

[Internal] List data centers

Retrieves a list of available data centers.

+
Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create data center

Creates a new data center.

+
Authorizations:
OAuth2
Request Body schema: application/json
required
name
required
string (DataCenterName)

The name of the data center.

+
label
required
string (DataCenterLabel)

The label of the data center.

+
logo
required
string (DataCenterLogo)

The logo of the data center.

+
location
required
string (DataCenterLocation)

The location of the data center.

+
provider
required
string (DataCenterProvider)

The provider of the data center.

+
zone
required
string (DataCenterZone)

The environment impact zone of the data center.

+
carbon_intensity
required
integer (DataCenterCarbonIntensity)

The environment impact carbon intensity of the data center.

+
green
required
boolean (DataCenterGreen)

The environment impact green of the data center.

+

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "logo": "string",
  • "location": "string",
  • "provider": "string",
  • "zone": "string",
  • "carbon_intensity": 0,
  • "green": true
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "logo": "string",
  • "location": "string",
  • "provider": "string",
  • "zone": "string",
  • "carbon_intensity": 0,
  • "green": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Get data center

Retrieves the specified data center.

+
Authorizations:
OAuth2
path Parameters
data_center_name
required
string

The name of the data center.

+

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "logo": "string",
  • "location": "string",
  • "provider": "string",
  • "zone": "string",
  • "carbon_intensity": 0,
  • "green": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Update data center

Updates the specified data center.

+
Authorizations:
OAuth2
path Parameters
data_center_name
required
string

The name of the data center.

+
Request Body schema: application/json
label
string (DataCenterLabel)

The label of the data center.

+
logo
string (DataCenterLogo)

The logo of the data center.

+
location
string (DataCenterLocation)

The location of the data center.

+
provider
string (DataCenterProvider)

The provider of the data center.

+
zone
string (DataCenterZone)

The environment impact zone of the data center.

+
carbon_intensity
integer (DataCenterCarbonIntensity)

The environment impact carbon intensity of the data center.

+
green
boolean (DataCenterGreen)

The environment impact green of the data center.

+

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "logo": "string",
  • "location": "string",
  • "provider": "string",
  • "zone": "string",
  • "carbon_intensity": 0,
  • "green": true
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "logo": "string",
  • "location": "string",
  • "provider": "string",
  • "zone": "string",
  • "carbon_intensity": 0,
  • "green": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

[Internal] Delete data center

Deletes the specified data center.

+
Authorizations:
OAuth2
path Parameters
data_center_name
required
string

The name of the data center.

+

Responses

Response samples

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

Http Traffic

[Internal] Gives an overview of HTTP Traffic for the apps

Authorizations:
OAuth2
path Parameters
projectId
required
string[a-z0-9]+
environmentId
required
string.+
query Parameters
from
required
integer <timestamp>
to
required
integer <timestamp>

Responses

Response samples

Content type
application/json
{
  • "_grain": 10,
  • "_from": 0,
  • "_to": 0,
  • "_project_id": "string",
  • "_environment_id": "string",
  • "_environment_type": "string",
  • "_branch_machine_name": "string",
  • "_top_urls_count": 10,
  • "data": {
    }
}

[Internal] Exposes observability entrypoint

Authorizations:
OAuth2
path Parameters
projectId
required
string[a-z0-9]+
environmentId
required
string.+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "project_id": "string",
  • "branch_machine_name": "string",
  • "environment_id": "string",
  • "environment_type": "string",
  • "vendor": "upsun",
  • "psh_user_identifier": "string",
  • "_links": {},
  • "retention": {
    },
  • "data_retention": {
    }
}

Logs

[Internal] Gives an overview of all apps and services

Authorizations:
OAuth2
path Parameters
projectId
required
string[a-z0-9]+
environmentId
required
string.+
query Parameters
from
required
integer <timestamp>
to
required
integer <timestamp>

Responses

Response samples

Content type
application/json
{
  • "_grain": 10,
  • "_from": 0,
  • "_to": 0,
  • "_project_id": "string",
  • "_environment_id": "string",
  • "_branch_machine_name": "string",
  • "data": [
    ],
  • "filters": {
    }
}

[Internal] Return the list of logs

Authorizations:
OAuth2
path Parameters
projectId
required
string[a-z0-9]+
environmentId
required
string.+
query Parameters
from
required
integer <timestamp>
to
required
integer <timestamp>
cursor
string <ulid>

Responses

Response samples

Content type
application/json
{
  • "_from": 0,
  • "_to": 0,
  • "_order": "DESC",
  • "_project_id": "string",
  • "_environment_id": "string",
  • "_branch_machine_name": "string",
  • "_cursor": "string",
  • "data": [
    ],
  • "filters": {
    }
}

[Internal] Exposes observability entrypoint

Authorizations:
OAuth2
path Parameters
projectId
required
string[a-z0-9]+
environmentId
required
string.+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "project_id": "string",
  • "branch_machine_name": "string",
  • "environment_id": "string",
  • "environment_type": "string",
  • "vendor": "upsun",
  • "psh_user_identifier": "string",
  • "_links": {},
  • "retention": {
    },
  • "data_retention": {
    }
}

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,
  • "local_disk_size": 0,
  • "cron_minimum_interval": 0,
  • "cron_maximum_jitter": 0,
  • "cron_production_expiry_interval": 0,
  • "cron_non_production_expiry_interval": 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,
  • "build_resources": {
    },
  • "outbound_restrictions_default_policy": "allow",
  • "self_upgrade": true,
  • "self_upgrade_latest_major": 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,
  • "enable_github_app_token_exchange": true,
  • "continuous_profiling": {
    },
  • "disable_agent_error_reporter": true,
  • "requires_domain_ownership": true,
  • "enable_guaranteed_resources": true,
  • "git_server": {
    },
  • "activity_logs_max_size": 0,
  • "allow_manual_deployments": true,
  • "allow_rolling_deployments": true,
  • "allow_burst": true,
  • "router_resources": {
    }
}

Update a project setting

Update one or more project-level settings.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
initialize
object (Initialization key)
object or null (Data retention configuration)

Data retention configuration

+
object (Build Resources)

Responses

Request samples

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

Response samples

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

get-projects-settings-chorus

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "exposed": true
}

update-projects-settings-chorus

Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
object (ChorusSettingsPatch)

Responses

Request samples

Content type
application/json
{ }

Response samples

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

delete-projects-settings-chorus

Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

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

Environment Settings

[Internal] These endpoints can be used to retrieve and manipulate environment-level +settings.

+

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

+

[Internal] List environment settings

List environment settings (for the time being, just Chorus settings).

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

Responses

Response samples

Content type
application/json
{
  • "chorus": {
    },
  • "enable_manual_deployments": true
}

[Internal] Update environment settings

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string
Request Body schema: application/json
required
enable_manual_deployments
boolean (Is manual deployments enabled)

Whether the environment uses manual deployments

+

Responses

Request samples

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

Response samples

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

[Internal] Delete environment settings

Authorizations:
OAuth2
path Parameters
projectId
required
string
environmentId
required
string

Responses

Response samples

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

Deployment Target

Upsun 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
required
One of
type
required
string (Deployment target type)
Enum: "dedicated" "enterprise" "local"

The type of the deployment target.

+
name
required
string (Deployment target name)

The name of the deployment target.

+
enforced_mounts
object (Enforced Mounts)

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
{
  • "id": "string",
  • "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
required
One of
type
required
string (Deployment target type)
Enum: "dedicated" "enterprise" "local"

The type of the deployment target.

+
name
required
string (Deployment target name)

The name of the deployment target.

+
enforced_mounts
object (Enforced Mounts)

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

[Internal] Trigger garbage collection on the Git repository

Triggers a git garbage collection operation which runs a number of +housekeeping tasks within the repository, such as compressing file +revisions (to reduce disk space and increase performance), removing +unreachable objects, packing refs, pruning reflog, rerere metadata, +or stale working trees.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

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

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
}

Container Profile

[Internal] These endpoints can be used to manage container settings like CPU and memory.

+

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

+

[Internal] Get list of configured container profiles for the project.

All container profiles available for the project. +Each profile is an object with a list of named pairs of CPU and memory that can be used by a service to define its resources. +They are used if sizing-api-enabled is set.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Internal] Create a new container profile

Add a new profile to the collection and make it available for sizing if flex-plans is enabled.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
Request Body schema: application/json
required
name
required
string (Name)

Container profile name

+
required
object (Sizes)

Container profile sizes

+

Responses

Request samples

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

Response samples

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

[Internal] Get a container profile

Retrieve a selected container profile based on containerProfileId. +The profile is an object with list of named pairs of CPU and memory used for sizing purposes.

+
Authorizations:
OAuth2
path Parameters
projectId
required
string
containerProfileId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "sizes": {
    }
}

[Internal] Update a container profile

Authorizations:
OAuth2
path Parameters
projectId
required
string
containerProfileId
required
string
Request Body schema: application/json
required
name
string (Name)

Container profile name

+
object (Sizes)

Container profile sizes

+

Responses

Request samples

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

Response samples

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

[Internal] Delete a container profile

Authorizations:
OAuth2
path Parameters
projectId
required
string
containerProfileId
required
string

Responses

Response samples

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

Risk

[Internal] Get user risk score

Retrieves risk factors for the user and calculates a score (e.g. for phone verification trigger).

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

The ID of the user.

+
query Parameters
token_iat
string <date-time>

Timestamp extracted from user token. Used to refresh phone_number_verified status when needed.

+
force_refresh
boolean

Whether the phone_number_verified flag should be refreshed. Should be set when KYC is called right after phone verification.

+

Responses

Response samples

Content type
application/json
{
  • "risk": "low",
  • "phone_number_verified": true,
  • "request_verification_staff": true
}

[Internal] Get explanation of risk evaluation

Get verbose explanation of risk score for investigation purposes.

+
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
{
  • "risk": {
    },
  • "trial-eligibility": {
    },
  • "normalized_email_count": 38,
  • "phone_number_count": 29
}

[Internal] Get free trial eligibility

Checks whether a user has already had a free trial using duplicate accounts.

+
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
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "trial_eligible": true
}

[Internal] Get staff verification information

Checks whether a user has been verified by staff, why, when and by whom.

+
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
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "verified": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe",
  • "notes": "User unable to receive SMS, but was manually checked and is legit."
}

[Internal] Update user's staff verification status

Updates user's staff verification status.

+
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
required
verified
boolean

Whether the user should be marked as staff verified.

+
notes
string

Reasons user is being verified.

+

Responses

Request samples

Content type
application/json
{
  • "verified": true,
  • "notes": "User unable to receive SMS, but was manually checked and is legit."
}

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "verified": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe",
  • "notes": "User unable to receive SMS, but was manually checked and is legit."
}

[Internal] Update user's suspicious status

Updates user's suspicious status.

+
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
required
suspicious
boolean

Whether the user should be marked as suspicious.

+
notes
string

Reasons user is being marked as suspicious.

+
level
integer

1 - Requires phone verification, 2 - Requires staff verification

+

Responses

Request samples

Content type
application/json
{
  • "suspicious": true,
  • "notes": "Typical email pattern.",
  • "level": 1
}

Response samples

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

[Internal] Get card testing stats for a specific user

Get card testing stats for a specific user for a specified period

+
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
{
  • "attempts": {
    },
  • "cards": {
    },
  • "countries": 0,
  • "period": "daily"
}

[Internal] Get email address risk evaluation

Get the IPQS based email address evaluation and suggested action for a specific user

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

The ID of the user.

+
query Parameters
force_refresh
boolean

Whether to request a fresh email score in case none is available.

+

Responses

Response samples

Content type
application/json
{
  • "score": {
    },
  • "info": {
    }
}

[Internal] Get ip address risk evaluation

Get the IPQS based IP address evaluation and suggested action for a specific user

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

The ID of the user.

+
query Parameters
force_refresh
boolean

Whether to request a fresh IP score in case none has been requested yet.

+

Responses

Response samples

Content type
application/json
{
  • "min_risk": 5,
  • "max_risk": 50,
  • "avg_risk": 25,
  • "recent_abuse": false,
  • "crawler": false,
  • "proxy": false,
  • "vpn": false,
  • "tor": false,
  • "active_vpn": false,
  • "active_tor": false,
  • "bot_status": false,
  • "num_ips": 22,
  • "high_risk_country": false,
  • "abuse_velocity": "none",
  • "clean": false,
  • "score": {
    }
}

[Internal] Get organization creation evaluation

Get whether user is allowed to create an organization based on vendor.

+
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
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "allow": true
}

[Internal] Get known customer score

Get evaluation of whether the customer is new to us or has a previous history.

+
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
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "score": "new",
  • "reason": "string"
}

[Internal] Get country specific settings

Get country specific fraud settings

+
Authorizations:
OAuth2

Responses

Response samples

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

[Internal] Create country specific settings

Create country specific fraud settings

+
Authorizations:
OAuth2
Request Body schema: application/json
required
country_code
string

2 digit country code.

+
high_risk
boolean

Whether the country is flagged as high risk.

+

Responses

Request samples

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

Response samples

Content type
application/json
[
  • [
    ]
]

[Internal] Delete country specific settings

Delete country specific fraud settings

+
Authorizations:
OAuth2
path Parameters
country
required
string

The 2 digit country code.

+

Responses

Response samples

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

[Internal] Update country specific settings

Update country specific fraud settings

+
Authorizations:
OAuth2
path Parameters
country
required
string

The 2 digit country code.

+
Request Body schema: application/json
required
high_risk
boolean

Whether the country is flagged as high risk.

+

Responses

Request samples

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

Response samples

Content type
application/json
[
  • [
    ]
]

[Internal] Get email risk scores

Get IPQS based email risk scores

+
Authorizations:
OAuth2
query Parameters
synced_at
string <date-time>

Retrieve score synced after a specific date and time

+
after
string

The pagination cursor.

+
count
integer [ 1 .. 1000 ]
Default: null

The number of scores to retrieve.

+

Responses

Response samples

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

[Internal] Get user scores

Get history of user scores returned by KYC

+
Authorizations:
OAuth2
query Parameters
filter[score]
string
Enum: "risk" "email" "ip" "trial-eligibility" "card-testing-hourly" "card-testing-daily" "card-testing-weekly" "card-testing-all_time"

Filter by score type

+
filter[user_id]
string <uuid>

Filter by user ID.

+
filter[revision_id][gt]
integer

Filter by revision ID (greater than).

+
filter[revision_id][gte]
integer

Filter by revision ID (greater than or equal).

+
filter[revision_id][lt]
integer

Filter by revision ID (lower than).

+
filter[revision_id][lte]
integer

Filter by revision ID (lower than or equal).

+
after
string

The pagination cursor.

+
before
string

The pagination cursor.

+
count
integer [ 1 .. 1000 ]
Default: null

The number of scores to retrieve.

+

Responses

Response samples

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

[Internal] Get organization scores

Get history of organization scores returned by KYC

+
Authorizations:
OAuth2
query Parameters
filter[score]
string
Enum: "payment-profile" "trial-eligibility" "payment-score"

Filter by score type.

+
filter[organization_id]
string <ulid>

Filter by organization ID.

+
filter[revision_id][gt]
integer

Filter by revision ID (greater than).

+
filter[revision_id][gte]
integer

Filter by revision ID (greater than or equal).

+
filter[revision_id][lt]
integer

Filter by revision ID (lower than).

+
filter[revision_id][lte]
integer

Filter by revision ID (lower than or equal).

+
after
string

The pagination cursor.

+
before
string

The pagination cursor.

+
count
integer [ 1 .. 1000 ]
Default: null

The number of scores to retrieve.

+

Responses

Response samples

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

[Internal] Get organization risk score

Returns risk assessment score for organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "risk": "low",
  • "phone_number_verified": true,
  • "credit_card_verified": true,
  • "request_verification_staff": true
}

[Internal] Get organization payment profile

Get the payment profile of a specific organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "organization_id": "string",
  • "profile": "default"
}

[Internal] Get organization payment score

Get the payment score of a specific organization.

+
Authorizations:
OAuth2
path Parameters
organization_id
required
string <ulid>

The ID of the organization.

+

Responses

Response samples

Content type
application/json
{
  • "min_risk": 1,
  • "max_risk": 50,
  • "avg_risk": 33,
  • "num_disputed": 0,
  • "num_success": 0,
  • "num_failed": 0
}
+ +
+
+
+
+ + + + +
+
+
Company
+ +
+
+
Regions
+ +
+
+
Connect
+ +
+
+ +
+
+ +
+
+
+
+
+
+
+
+
+ +
+
+

© 2025 Upsun.com. All rights reserved.

+
+
+ +
+
+
+
+ + diff --git a/shared/pages/api.html b/shared/pages/api.html index cb01431612..55d6ed8662 100644 --- a/shared/pages/api.html +++ b/shared/pages/api.html @@ -19,35 +19,35 @@ -