Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Upsun.com Rest Project API
version: '1.0'
contact:
name: Support
url: https://upsun.com/contact-us/
termsOfService: https://upsun.com/trust-center/legal/tos/
description: "# Introduction\n\nUpsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API\nis simply Git. With a single `git push` and a couple of YAML files in\nyour repository you can deploy an arbitrarily complex cluster.\nEvery [**Project**](#tag/Project) can have multiple applications (PHP,\nNode.js, Python, Ruby, Go, etc.) and managed, automatically\nprovisioned services (databases, message queues, etc.).\n\nEach project also comes with multiple concurrent\nlive staging/development [**Environments**](#tag/Environment).\nThese ephemeral development environments\nare automatically created every time you push a new branch or create a\npull request, and each has a full copy of the data of its parent branch,\nwhich is created on-the-fly in seconds.\n\nOur Git implementation supports integrations with third party Git\nproviders such as GitHub, Bitbucket, or GitLab, allowing you to simply\nintegrate Upsun into your existing workflow.\n\n## Using the REST API\n\nIn addition to the Git API, we also offer a REST API that allows you to manage\nevery aspect of the platform, from managing projects and environments,\nto accessing accounts and subscriptions, to creating robust workflows\nand integrations with your CI systems and internal services.\n\nThese API docs are generated from a standard **OpenAPI (Swagger)** Specification document\nwhich you can find here in [YAML](openapispec-upsun.yaml) and in [JSON](openapispec-upsun.json) formats.\n\nThis RESTful API consumes and produces HAL-style JSON over HTTPS,\nand any REST library can be used to access it. On GitHub, we also host\na few API libraries that you can use to make API access easier, such as our\n[PHP API client](https://github.com/upsun/upsun-sdk-php).\n\nIn order to use the API you will first need to have an [Upsun account](https://auth.upsun.com/register/)\nand [create an API Token](https://docs.upsun.com/anchors/cli/api-token/).\n\n# Authentication\n\n## OAuth2\n\nAPI authentication is done with OAuth2 access tokens.\n\n### API tokens\n\nYou can use an API token as one way to get an OAuth2 access token. This\nis particularly useful in scripts, e.g. for CI pipelines.\n\nTo create an API token, go to the \"API Tokens\" section\nof the \"Account Settings\" tab on the [Console](https://console.upsun.com).\n\nTo exchange this API token for an access token, a `POST` request\nmust be made to `https://auth.upsun.com/oauth2/token`.\n\nThe request will look like this in cURL:\n\n<pre>\ncurl -u platform-api-user: \\\n -d 'grant_type=api_token&api_token=<em><b>API_TOKEN</b></em>' \\\n https://auth.upsun.com/oauth2/token\n</pre>\n\nThis will return a \"Bearer\" access token that\ncan be used to authenticate further API requests, for example:\n\n<pre>\n{\n \"access_token\": \"<em><b>abcdefghij1234567890</b></em>\",\n \"expires_in\": 900,\n \"token_type\": \"bearer\"\n}\n</pre>\n\n### Using the Access Token\n\nTo authenticate further API requests, include this returned bearer token\nin the `Authorization` header. For example, to retrieve a list of\n[Projects](#tag/Project)\naccessible by the current user, you can make the following request\n(substituting the dummy token for your own):\n\n<pre>\ncurl -H \"Authorization: Bearer <em><b>abcdefghij1234567890</b></em>\" \\\n https://api.upsun.com/projects\n</pre>\n\n# HAL Links\n\nMost endpoints in the API return fields which defines a HAL\n(Hypertext Application Language) schema for the requested endpoint.\nThe particular objects returns and their contents can vary by endpoint.\nThe payload examples we give here for the requests do not show these\nelements. These links can allow you to create a fully dynamic API client\nthat does not need to hardcode any method or schema.\n\nUnless they are used for pagination we do not show the HAL links in the\npayload examples in this documentation for brevity and as their content\nis contextual (based on the permissions of the user).\n\n## _links Objects\n\nMost endpoints that respond to `GET` requests will include a `_links` object\nin their response. The `_links` object contains a key-object pair labelled `self`, which defines\ntwo further key-value pairs:\n\n* `href` - A URL string referring to the fully qualified name of the returned object. For many endpoints, this will be the direct link to the API endpoint on the region gateway, rather than on the general API gateway. This means it may reference a host of, for example, `eu-2.platform.sh` rather than `api.upsun.com`.\n* `meta` - An object defining the OpenAPI Specification (OAS) [schema object](https://swagger.io/specification/#schemaObject) of the component returned by the endpoint.\n\nThere may be zero or more other fields in the `_links` object resembling fragment identifiers\nbeginning with a hash mark, e.g. `#edit` or `#delete`. Each of these keys\nrefers to a JSON object containing two key-value pairs:\n\n* `href` - A URL string referring to the path name of endpoint which can perform the action named in the key.\n* `meta` - An object defining the OAS schema of the endpoint. This consists of a key-value pair, with the key defining an HTTP method and the value defining the [operation object](https://swagger.io/specification/#operationObject) of the endpoint.\n\nTo use one of these HAL links, you must send a new request to the URL defined\nin the `href` field which contains a body defined the schema object in the `meta` field.\n\nFor example, if you make a request such as `GET /projects/abcdefghij1234567890`, the `_links`\nobject in the returned response will include the key `#delete`. That object\nwill look something like this fragment:\n\n```\n\"#delete\": {\n \"href\": \"/api/projects/abcdefghij1234567890\",\n \"meta\": {\n \"delete\": {\n \"responses\": {\n . . . // Response definition omitted for space\n },\n \"parameters\": []\n }\n }\n}\n```\n\nTo use this information to delete a project, you would then send a `DELETE`\nrequest to the endpoint `https://api.upsun.com/api/projects/abcdefghij1234567890`\nwith no body or parameters to delete the project that was originally requested.\n\n## _embedded Objects\n\nRequests to endpoints which create or modify objects, such as `POST`, `PATCH`, or `DELETE`\nrequests, will include an `_embedded` key in their response. The object\nrepresented by this key will contain the created or modified object. This\nobject is identical to what would be returned by a subsequent `GET` request\nfor the object referred to by the endpoint.\n"
x-logo:
url: https://docs.upsun.com/images/upsun-api.svg
href: https://upsun.com/#section/Introduction
altText: Upsun logo
servers:
- url: '{schemes}://api.upsun.com'
description: The Upsun.com API gateway
variables:
schemes:
default: https
security:
- BearerAuth: []
tags:
- name: Project
description: '## 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](#tag/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](#tag/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`](#tag/Subscriptions).
'
paths:
/projects/{projectId}:
get:
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: get-projects
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
tags:
- Project
summary: Get a project
description: Retrieve the details of a single project.
/projects/{projectId}/capabilities:
get:
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: get-projects-capabilities
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectCapabilities'
tags:
- Project
summary: Get a project's capabilities
description: '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.
'
/projects/{projectId}/clear_build_cache:
post:
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: action-projects-clear-build-cache
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponse'
tags:
- Project
summary: Clear project build cache
description: '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.](https://docs.upsun.com/anchors/troubleshoot/clear-build-cache/)
'
/projects/{projectId}/maintenance-redeploy:
post:
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: maintenance-redeploy-project
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponse'
tags:
- Project
components:
schemas:
ProjectCapabilities:
type: object
properties:
custom_domains:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, custom domains can be added to the project.
environments_with_domains_limit:
type: integer
title: Domains limit
description: Limit on the amount of non-production environments that can have domains set
required:
- enabled
- environments_with_domains_limit
additionalProperties: false
title: Custom Domains
description: ''
source_operations:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, source operations can be triggered.
required:
- enabled
additionalProperties: false
title: Source Operations
description: ''
runtime_operations:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, runtime operations can be triggered.
required:
- enabled
additionalProperties: false
title: Runtime Operations
description: ''
tasks:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, background tasks can be triggered.
required:
- enabled
additionalProperties: false
title: Tasks
description: ''
outbound_firewall:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, outbound firewall can be used.
required:
- enabled
additionalProperties: false
title: Outbound Firewall
description: ''
egress_proxy:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: 'If true, the egress proxy is on for every container in the project: outbound traffic is denied by default and must traverse the proxy. Applies project-wide regardless of whether an application declares an egress allowlist.'
required:
- enabled
additionalProperties: false
title: Egress Proxy
description: ''
metrics:
type: object
properties:
max_range:
type: string
title: Max range
description: Limit on the maximum time range allowed in metrics retrieval
required:
- max_range
additionalProperties: false
title: Metrics
description: ''
logs_forwarding:
type: object
properties:
max_extra_payload_size:
type: integer
title: Max extra payload size
description: Limit on the maximum size for the custom extra attributes added to the forwarded logs payload
required:
- max_extra_payload_size
additionalProperties: false
title: Logs Forwarding
description: ''
guaranteed_resources:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, guaranteed resources can be used
instance_limit:
type: integer
title: Instance limit
description: Instance limit for guaranteed resources
required:
- enabled
- instance_limit
additionalProperties: false
title: Guaranteed Resources
description: ''
images:
type: object
additionalProperties:
type: object
additionalProperties:
type: object
properties:
available:
type: boolean
title: Available
description: The image is available for deployment
required:
- available
additionalProperties: false
title: Images
description: ''
instance_limit:
type: integer
title: Instance limit
description: Maximum number of instance per service
build_resources:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, build resources can be modified.
max_cpu:
type: number
format: float
title: CPU
description: ''
max_memory:
type: integer
title: Memory
description: ''
required:
- enabled
- max_cpu
- max_memory
additionalProperties: false
title: Build Resources
description: ''
object_storage:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, implicit object-storage can be used.
min_storage:
type: integer
title: Minimum storage
description: Lower bound for the size of implicit object-storage on the project, in MiB.
max_storage:
type: integer
title: Maximum storage
description: Upper bound for the size of implicit object-storage on the project, in MiB.
storage_step:
type: integer
title: Storage step
description: Granularity of implicit object-storage allocations, in MiB. resources.disk.object, min_storage and max_storage must all be multiples of this value.
cpu_per_step:
type: number
format: float
title: CPU per step
description: CPU granted to the implicit object-storage service for each storage_step of allocated quota.
memory_per_step:
type: integer
title: Memory per step
description: Memory granted to the implicit object-storage service for each storage_step of allocated quota, in MiB.
max_cpu:
type: number
format: float
title: Maximum CPU
description: Upper bound on the CPU granted to the implicit object-storage service, regardless of the configured quota.
max_memory:
type: integer
title: Maximum memory
description: Upper bound on the memory granted to the implicit object-storage service, in MiB, regardless of the configured quota.
required:
- enabled
- min_storage
- max_storage
- storage_step
- cpu_per_step
- memory_per_step
- max_cpu
- max_memory
additionalProperties: false
title: Object Storage
description: ''
data_retention:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, data retention configuration can be modified.
required:
- enabled
additionalProperties: false
title: Data Retention
description: ''
autoscaling:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, autoscaling can be configured.
supports_horizontal_scaling_services:
type: boolean
title: Enable autoscaling for services
description: Allow autoscaling to be configured for services (not just apps and workers)
required:
- enabled
- supports_horizontal_scaling_services
additionalProperties: false
title: Autoscaling
description: ''
integrations:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: If true, integrations can be used
config:
type: object
properties:
newrelic:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: New Relic
description: New Relic log-forwarding integration configurations
sumologic:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Sumo Logic
description: Sumo Logic log-forwarding integration configurations
splunk:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Splunk
description: Splunk log-forwarding integration configurations
httplog:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: HTTP log-forwarding
description: HTTP log-forwarding integration configurations
syslog:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Syslog
description: Syslog log-forwarding integration configurations
webhook:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Webhook
description: Webhook integration configurations
script:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Script
description: Script integration configurations
github:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: GitHub
description: GitHub integration configurations
gitlab:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: GitLab
description: GitLab integration configurations
bitbucket:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Bitbucket
description: Bitbucket integration configurations
bitbucket_server:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Bitbucket Server
description: Bitbucket server integration configurations
health.email:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Health Email
description: Health Email notification integration configurations
health.webhook:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Health WebHook
description: Health Webhook notification integration configurations
health.pagerduty:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Health PagerDuty
description: Health PagerDuty notification integration configurations
health.slack:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Health Slack
description: Health Slack notification integration configurations
cdn.fastly:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Fastly CDN
description: Fastly CDN integration configurations
blackfire:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: Blackfire
description: Blackfire integration configurations
otlplog:
type: object
properties:
enabled:
type: boolean
title: Enabled
description: The integration is enabled.
role:
type: string
title: Role
description: Minimum required role for creating the integration.
additionalProperties: false
title: OpenTelemetry
description: OpenTelemetry log-forwarding integration configurations
additionalProperties: false
title: Config
description: ''
allowed_integrations:
type: array
items:
type: string
title: Allowed Integrations
description: List of integrations allowed to be created
required:
- enabled
additionalProperties: false
title: Integrations
description: ''
required:
- tasks
- metrics
- logs_forwarding
- guaranteed_resources
- images
- instance_limit
- build_resources
- object_storage
- data_retention
- autoscaling
additionalProperties: false
AcceptedResponse:
type: object
properties:
status:
type: string
title: Status text
description: The status text of the response
code:
type: integer
title: Status code
description: The status code of the response
required:
- status
- code
additionalProperties: false
Project:
type: object
properties:
id:
type: string
title: Project Identifier
description: The identifier of Project
created_at:
type:
- string
- 'null'
format: date-time
title: Creation date
description: The creation date
updated_at:
type:
- string
- 'null'
format: date-time
title: Update date
description: The update date
attributes:
type: object
additionalProperties:
type: string
title: Arbitrary attributes
description: Arbitrary attributes attached to this resource
title:
type: string
title: Title
description: The title of the project
description:
type: string
title: Description
description: The description of the project
owner:
type: string
title: Owner
description: The owner of the project
deprecated: true
x-stability: DEPRECATED
namespace:
type:
- string
- 'null'
title: Namespace
description: The namespace the project belongs in
x-stability: EXPERIMENTAL
organization:
type:
- string
- 'null'
title: Organi
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/platform.sh/refs/heads/main/openapi/platform.sh-project-api-openapi.yml