Upsun Project API
## 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).
Documentation
Specifications
openapi: 3.0.1
info:
title: Upsun.com Rest Add-ons 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:
- OAuth2: []
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.
patch:
requestBody:
description: ''
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectPatch'
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: update-projects
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponse'
tags:
- Project
summary: Update a project
description: Update the details of an existing project.
delete:
parameters:
- in: path
required: true
schema:
type: string
name: projectId
operationId: delete-projects
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponse'
tags:
- Project
summary: Delete a project
description: Delete the entire 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/)
'
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: ''
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: ''
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: ''
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.
required:
- enabled
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.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:
- metrics
- logs_forwarding
- guaranteed_resources
- images
- instance_limit
- build_resources
- data_retention
- autoscaling
additionalProperties: false
Project:
type: object
properties:
id:
type: string
title: Project Identifier
description: The identifier of Project
created_at:
type: string
format: date-time
nullable: true
title: Creation date
description: The creation date
updated_at:
type: string
format: date-time
nullable: true
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
nullable: true
title: Namespace
description: The namespace the project belongs in
x-stability: EXPERIMENTAL
organization:
type: string
nullable: true
title: Organization
description: The organization the project belongs in
x-stability: EXPERIMENTAL
default_branch:
type: string
nullable: true
title: Default branch
description: The default branch of the project
status:
type: object
properties:
code:
type: string
title: Status code
description: ''
message:
type: string
title: Status text
description: ''
required:
- code
- message
additionalProperties: false
title: Status
description: The status of the project
timezone:
type: string
title: Timezone
description: Timezone of the project
region:
type: string
title: Region
description: The region of the project
repository:
type: object
properties:
url:
type: string
title: Git URL
description: ''
client_ssh_key:
type: string
nullable: true
title: SSH Key
description: SSH Key used to access external private repositories.
required:
- url
- client_ssh_key
additionalProperties: false
title: Repository information
description: The repository information of the project
default_domain:
type: string
nullable: true
title: Default domain
description: The default domain of the project
subscription:
type: object
properties:
license_uri:
type: string
title: Subscription URI
description: URI of the subscription
plan:
type: string
enum:
- 2xlarge
- 2xlarge-high-memory
- 4xlarge
- 8xlarge
- development
- large
- large-high-memory
- medium
- medium-high-memory
- standard
- standard-high-memory
- xlarge
- xlarge-high-memory
title: Plan level
description: ''
environments:
type: integer
title: Environments number
description: Number of environments
storage:
type: integer
title: Storage
description: Size of storage (in MB)
included_users:
type: integer
title: Included users
description: Number of users
subscription_management_uri:
type: string
title: Subscription management URI
description: URI for managing the subscription
restricted:
type: boolean
title: Is subscription attribute
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upsun/refs/heads/main/openapi/upsun-project-api-openapi.yml