Platform.sh Deployment API

openapi: 3.2.0
info:
  title: Upsun.com Rest Deployment 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&amp;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: Deployment
paths:
  /projects/{projectId}/environments/{environmentId}/deployments:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      operationId: list-projects-environments-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentCollection'
      tags:
      - Deployment
      summary: Get an environment's deployment information
      description: '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.

        '
  /projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      - in: path
        required: true
        schema:
          type: string
        name: deploymentId
      operationId: get-projects-environments-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
      tags:
      - Deployment
      summary: Get a single environment deployment
      description: 'Retrieve a single deployment configuration with an id of `current`. This may be subject to change in the future.

        Only `current` can be queried.

        '
components:
  schemas:
    ProxyRoute:
      type: object
      properties:
        id:
          type: string
          title: ProxyRoute Identifier
          description: The identifier of ProxyRoute
        primary:
          type:
          - boolean
          - 'null'
          title: Is primary
          description: This route is the primary route of the environment
        production_url:
          type:
          - string
          - 'null'
          title: Production URL
          description: How this URL route would look on production environment
        attributes:
          type: object
          additionalProperties:
            type: string
          title: Arbitrary attributes
          description: Arbitrary attributes attached to this resource
        type:
          type: string
          enum:
          - proxy
          - redirect
          - upstream
          title: Route type
          description: Route type
        tls:
          type: object
          properties:
            strict_transport_security:
              type: object
              properties:
                enabled:
                  type:
                  - boolean
                  - 'null'
                  title: Is enabled
                  description: Whether strict transport security is enabled or not
                include_subdomains:
                  type:
                  - boolean
                  - 'null'
                  title: Is subdomains included
                  description: Whether the strict transport security policy should include all subdomains
                preload:
                  type:
                  - boolean
                  - 'null'
                  title: Is strict transport security preloaded
                  description: Whether the strict transport security policy should be preloaded in browsers
              required:
              - enabled
              - include_subdomains
              - preload
              additionalProperties: false
              title: Strict-Transport-Security options.
              description: ''
            min_version:
              type:
              - string
              - 'null'
              enum:
              - TLSv1.0
              - TLSv1.1
              - TLSv1.2
              - TLSv1.3
              title: Minimum TLS version
              description: The minimum TLS version to support.
            client_authentication:
              type:
              - string
              - 'null'
              enum:
              - request
              - require
              title: Client authentication
              description: The type of client authentication to request.
            client_certificate_authorities:
              type: array
              items:
                type: string
              title: Client certificate authorities
              description: Certificate authorities to validate the client certificate against. If not specified, a default set of trusted CAs will be used.
          required:
          - strict_transport_security
          - min_version
          - client_authentication
          - client_certificate_authorities
          additionalProperties: false
          title: TLS settings
          description: TLS settings for the route
        to:
          type: string
          title: Proxy destination
          description: The destination of the proxy
      required:
      - primary
      - id
      - production_url
      - attributes
      - type
      - tls
      - to
      additionalProperties: false
    RedirectRoute:
      type: object
      properties:
        id:
          type: string
          title: RedirectRoute Identifier
          description: The identifier of RedirectRoute
        primary:
          type:
          - boolean
          - 'null'
          title: Is primary
          description: This route is the primary route of the environment
        production_url:
          type:
          - string
          - 'null'
          title: Production URL
          description: How this URL route would look on production environment
        attributes:
          type: object
          additionalProperties:
            type: string
          title: Arbitrary attributes
          description: Arbitrary attributes attached to this resource
        type:
          type: string
          enum:
          - proxy
          - redirect
          - upstream
          title: Route type
          description: Route type
        tls:
          type: object
          properties:
            strict_transport_security:
              type: object
              properties:
                enabled:
                  type:
                  - boolean
                  - 'null'
                  title: Is enabled
                  description: Whether strict transport security is enabled or not
                include_subdomains:
                  type:
                  - boolean
                  - 'null'
                  title: Is subdomains included
                  description: Whether the strict transport security policy should include all subdomains
                preload:
                  type:
                  - boolean
                  - 'null'
                  title: Is strict transport security preloaded
                  description: Whether the strict transport security policy should be preloaded in browsers
              required:
              - enabled
              - include_subdomains
              - preload
              additionalProperties: false
              title: Strict-Transport-Security options.
              description: ''
            min_version:
              type:
              - string
              - 'null'
              enum:
              - TLSv1.0
              - TLSv1.1
              - TLSv1.2
              - TLSv1.3
              title: Minimum TLS version
              description: The minimum TLS version to support.
            client_authentication:
              type:
              - string
              - 'null'
              enum:
              - request
              - require
              title: Client authentication
              description: The type of client authentication to request.
            client_certificate_authorities:
              type: array
              items:
                type: string
              title: Client certificate authorities
              description: Certificate authorities to validate the client certificate against. If not specified, a default set of trusted CAs will be used.
          required:
          - strict_transport_security
          - min_version
          - client_authentication
          - client_certificate_authorities
          additionalProperties: false
          title: TLS settings
          description: TLS settings for the route
        to:
          type: string
          title: Redirect destination
          description: The destination of the proxy
        redirects:
          type: object
          properties:
            expires:
              type: string
              title: Expires
              description: The amount of time, in seconds, to cache the redirects
            paths:
              type: object
              additionalProperties:
                type: object
                properties:
                  regexp:
                    type: boolean
                    title: Is regexp
                    description: Whether the path is a regular expression.
                  to:
                    type: string
                    title: Redirect URL
                    description: The URL to redirect to.
                  prefix:
                    type:
                    - boolean
                    - 'null'
                    title: Is prefix
                    description: Whether to redirect all the paths that start with the path.
                  append_suffix:
                    type:
                    - boolean
                    - 'null'
                    title: Append suffix
                    description: Whether to append the incoming suffix to the redirected URL.
                  code:
                    type: integer
                    enum:
                    - 301
                    - 302
                    - 307
                    - 308
                    title: Redirect code
                    description: The redirect code to use.
                  expires:
                    type:
                    - string
                    - 'null'
                    title: Expires
                    description: The amount of time, in seconds, to cache the redirects.
                required:
                - regexp
                - to
                - prefix
                - append_suffix
                - code
                - expires
                additionalProperties: false
              title: Path
              description: The paths to redirect
          required:
          - expires
          - paths
          additionalProperties: false
          title: Redirect configuration
          description: The configuration of the redirects
      required:
      - primary
      - id
      - production_url
      - attributes
      - type
      - tls
      - to
      - redirects
      additionalProperties: false
    Deployment:
      type: object
      properties:
        id:
          type: string
          title: Deployment Identifier
          description: The identifier of Deployment
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Creation date
          description: The creation date of the deployment
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Update date
          description: The update date of the deployment
        fingerprint:
          type: string
          title: Deployment fingerprint
          description: The fingerprint of the deployment
        cluster_name:
          type: string
          title: Cluster name
          description: The name of the cluster
        project_info:
          type: object
          properties:
            title:
              type: string
              title: Title
              description: ''
            name:
              type: string
              title: Name
              description: ''
            namespace:
              type:
              - string
              - 'null'
              title: Namespace
              description: ''
            organization:
              type:
              - string
              - 'null'
              title: Organization
              description: ''
            capabilities:
              type: object
              title: Capabilities
              description: ''
            settings:
              type: object
              title: Settings
              description: ''
          required:
          - title
          - name
          - namespace
          - organization
          - capabilities
          - settings
          additionalProperties: false
          title: Project info
          description: The project information
        environment_info:
          type: object
          properties:
            name:
              type: string
              title: Environment name
              description: The machine name of the environment
            status:
              type: string
              title: Environment status
              description: The enviroment status
            is_main:
              type: boolean
              title: Is main environment
              description: Is this environment the main environment
            is_production:
              type: boolean
              title: Is production environment
              description: Is this environment a production environment
            constraints:
              type: object
              title: Environment constraints
              description: Constraints of the environment's deployment
            reference:
              type: string
              title: Git reference
              description: The reference in Git for this environment
            machine_name:
              type: string
              title: Machine name
              description: The machine name of the environment
            environment_type:
              type: string
              title: Environment type
              description: The type of environment (Production, Staging or Development)
            links:
              type: object
              title: Links
              description: ''
          required:
          - name
          - status
          - is_main
          - is_production
          - constraints
          - reference
          - machine_name
          - environment_type
          - links
          additionalProperties: false
          title: Environment info
          description: The environment information
        deployment_target:
          type: string
          title: Deployment target
          description: The deployment target
        vpn:
          type:
          - object
          - 'null'
          properties:
            version:
              type: integer
              enum:
              - 1
              - 2
              title: IKE Version
              description: The IKE version to use (1 or 2)
            aggressive:
              type: string
              enum:
              - 'no'
              - 'yes'
              title: Aggressive Mode
              description: Whether to use IKEv1 Aggressive or Main Mode
            modeconfig:
              type: string
              enum:
              - pull
              - push
              title: Mode Config
              description: Defines which mode is used to assign a virtual IP (must be the same on both sides)
            authentication:
              type: string
              title: Authentication scheme
              description: The authentication scheme
            gateway_ip:
              type: string
              title: Remote gateway IP
              description: ''
            identity:
              type:
              - string
              - 'null'
              title: Identity
              description: The identity of the ipsec participant
            second_identity:
              type:
              - string
              - 'null'
              title: Second Identity
              description: The second identity of the ipsec participant
            remote_identity:
              type:
              - string
              - 'null'
              title: Remote Identity
              description: The identity of the remote ipsec participant
            remote_subnets:
              type: array
              items:
                type: string
              title: Remote Subnets
              description: Remote subnets (CIDR notation)
            ike:
              type: string
              title: IKE algorithms
              description: The IKE algorithms to negotiate for this VPN connection.
            esp:
              type: string
              title: ESP algorithms
              description: The ESP algorithms to negotiate for this VPN connection.
            ikelifetime:
              type: string
              title: IKE Lifetime
              description: The lifetime of the IKE exchange.
            lifetime:
              type: string
              title: ESP Lifetime
              description: The lifetime of the ESP exchange.
            margintime:
              type: string
              title: Margin Time
              description: The margin time for re-keying.
          required:
          - version
          - aggressive
          - modeconfig
          - authentication
          - gateway_ip
          - identity
          - second_identity
          - remote_identity
          - remote_subnets
          - ike
          - esp
          - ikelifetime
          - lifetime
          - margintime
          additionalProperties: false
          title: VPN configuration
          description: The configuration of the VPN
        http_access:
          type: object
          properties:
            is_enabled:
              type: boolean
              title: Is enabled
              description: Whether http_access control is enabled
            addresses:
              type: array
              items:
                type: object
                properties:
                  permission:
                    type: string
                    enum:
                    - allow
                    - deny
                    title: Permission
                    description: ''
                  address:
                    type: string
                    title: Address
                    description: IP address or CIDR
                required:
                - permission
                - address
                additionalProperties: false
              title: Address grants
              description: ''
            basic_auth:
              type: object
              additionalProperties:
                type: string
              title: Basic auth grants
              description: ''
          required:
          - is_enabled
          - addresses
          - basic_auth
          additionalProperties: false
          title: HTTP access permissions
          description: The permissions of the HTTP access
        enable_smtp:
          type: boolean
          title: Enable SMTP
          description: Whether to configure SMTP for this environment
        restrict_robots:
          type: boolean
          title: Restrict robots
          description: Whether to restrict robots for this environment
        variables:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                title: Variable name
                description: Name of the variable
              value:
                type: string
                title: Variable value
                description: Value of the variable
              is_sensitive:
                type: boolean
                title: Is sensitive
                description: The variable is sensitive
              is_json:
                type: boolean
                title: Is JSON
                description: The variable is a JSON string
              visible_build:
                type: boolean
                title: Visible at build time
                description: The variable is visible during build
              visible_runtime:
                type: boolean
                title: Visible at runtime
                description: The variable is visible at runtime
            required:
            - name
            - is_sensitive
            - is_json
            - visible_build
            - visible_runtime
            additionalProperties: false
          title: Environment variables
          description: The variables applying to this environment
        access:
          type: array
          items:
            type: object
            properties:
              entity_id:
                type: string
                title: Entity ID
                description: ''
              role:
                type: string
                enum:
                - admin
                - contributor
                - viewer
                title: Role
                description: ''
            required:
            - entity_id
            - role
            additionalProperties: false
          title: Access control
          description: Access control definition for this enviroment
        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 attributes frozen
              description: True if subscription attributes, like number of users, are frozen
            suspended:
              type: boolean
              title: Is subscription suspended
              description: Whether or not the subscription is suspended
            user_licenses:
              type: integer
              title: Current number of users
              description: Current number of users
            resources:
              type: object
              properties:
                container_profiles:
                  type: boolean
                  title: Is Container profiles enabled
                  description: Enable support for customizable container profiles
                production:
                  type: object
                  properties:
                    legacy_development:
                      type: boolean
                      title: Legacy development sizing
                      description: Enable legacy development sizing for this environment type
                    max_cpu:
                      type:
                      - number
                      - 'null'
                      format: float
                      title: Maximum CPU units
                      description: Maximum number of allocated CPU units
                    max_memory:
                      type:
                      - integer
                      - 'null'
                      title: Maximum RAM
                      description: Maximum amount of allocated RAM
                    max_environments:
                      type:
                      - integer
                      - 'null'
                      title: Maximum environments
                      description: Maximum number of environments
                  required:
                  - legacy_development
                  - max_cpu
                  - max_memory
                  - max_environments
                  additionalProperties: false
                  title: Production resources
                  description: Resources for production environments
                development:
                  ty

# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/platform.sh/refs/heads/main/openapi/platform.sh-deployment-api-openapi.yml