Platform.sh Deployment Target API

openapi: 3.2.0
info:
  title: Upsun.com Rest Deployment Target 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 Target
  description: '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.

    '
paths:
  /projects/{projectId}/deployments:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      operationId: list-projects-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentTargetCollection'
      tags:
      - Deployment Target
      summary: Get project deployment target info
      description: 'The deployment target information for the project.

        '
    post:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      operationId: create-projects-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentTargetCreateInput'
      tags:
      - Deployment Target
      summary: Create a project deployment target
      description: 'Set the deployment target information for a project.

        '
  /projects/{projectId}/deployments/{deploymentTargetConfigurationId}:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: deploymentTargetConfigurationId
      operationId: get-projects-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentTarget'
      tags:
      - Deployment Target
      summary: Get a single project deployment target
      description: 'Get a single deployment target configuration of a project.

        '
    patch:
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentTargetPatch'
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: deploymentTargetConfigurationId
      operationId: update-projects-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      tags:
      - Deployment Target
      summary: Update a project deployment
    delete:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: deploymentTargetConfigurationId
      operationId: delete-projects-deployments
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      tags:
      - Deployment Target
      summary: Delete a single project deployment target
      description: 'Delete a single deployment target configuration associated with a specific project.

        '
components:
  schemas:
    KubernetesDeploymentTargetStorageCreateInput:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
      required:
      - type
      - name
      additionalProperties: false
    DedicatedDeploymentTargetCreateInput:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        enforced_mounts:
          type: object
          title: Enforced Mounts
          description: Mounts which are always injected into pushed (e.g. enforce /var/log to be a local mount)
      required:
      - type
      - name
      additionalProperties: false
    DedicatedDeploymentTarget:
      type: object
      properties:
        id:
          type: string
          title: DedicatedDeploymentTarget Identifier
          description: The identifier of DedicatedDeploymentTarget
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        deploy_host:
          type:
          - string
          - 'null'
          title: Host
          description: The host to deploy to
        deploy_port:
          type:
          - integer
          - 'null'
          title: Port
          description: The port to deploy to
        ssh_host:
          type:
          - string
          - 'null'
          title: SSH Host
          description: The host to use to SSH to app containers
        hosts:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              id:
                type:
                - string
                - 'null'
                title: Host identifier
                description: The identifier of the host.
              type:
                type: string
                enum:
                - core
                - satellite
                title: Deployment type
                description: The type of the deployment to this host.
              services:
                type:
                - array
                - 'null'
                items:
                  type: string
                title: Assigned services
                description: The services assigned to this host
            required:
            - id
            - type
            - services
            additionalProperties: false
          title: Hosts
          description: The hosts of the deployment target
        auto_mounts:
          type: boolean
          title: Auto Mounts
          description: Whether to take application mounts from the pushed data or the deployment target
        excluded_mounts:
          type: array
          items:
            type: string
          title: Excluded Mounts
          description: Directories that should not be mounted
        enforced_mounts:
          type: object
          title: Enforced Mounts
          description: Mounts which are always injected into pushed (e.g. enforce /var/log to be a local mount)
        auto_crons:
          type: boolean
          title: Auto Crons
          description: Whether to take application crons from the pushed data or the deployment target
        auto_nginx:
          type: boolean
          title: Auto Nginx
          description: Whether to take application crons from the pushed data or the deployment target
        maintenance_mode:
          type: boolean
          title: Maintenance Mode
          description: Whether to perform deployments or not
        guardrails_phase:
          type: integer
          title: Guardrails Phase
          description: which phase of guardrails are we in
      required:
      - type
      - name
      - deploy_host
      - deploy_port
      - ssh_host
      - hosts
      - auto_mounts
      - excluded_mounts
      - enforced_mounts
      - auto_crons
      - auto_nginx
      - maintenance_mode
      - guardrails_phase
      additionalProperties: false
    DeploymentTargetCreateInput:
      oneOf:
      - $ref: '#/components/schemas/DedicatedDeploymentTargetCreateInput'
      - $ref: '#/components/schemas/EnterpriseDeploymentTargetCreateInput'
      - $ref: '#/components/schemas/FoundationDeploymentTargetCreateInput'
      - $ref: '#/components/schemas/KubernetesDeploymentTargetStorageCreateInput'
    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
    DedicatedDeploymentTargetPatch:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        enforced_mounts:
          type: object
          title: Enforced Mounts
          description: Mounts which are always injected into pushed (e.g. enforce /var/log to be a local mount)
      required:
      - type
      - name
      additionalProperties: false
    FoundationDeploymentTarget:
      type: object
      properties:
        id:
          type: string
          title: FoundationDeploymentTarget Identifier
          description: The identifier of FoundationDeploymentTarget
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        hosts:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              id:
                type:
                - string
                - 'null'
                title: Host identifier
                description: The identifier of the host.
              type:
                type: string
                enum:
                - core
                - satellite
                title: Deployment type
                description: The type of the deployment to this host.
              services:
                type:
                - array
                - 'null'
                items:
                  type: string
                title: Assigned services
                description: The services assigned to this host
            required:
            - id
            - type
            - services
            additionalProperties: false
          title: Deployment hosts
          description: The hosts of the deployment target
        use_dedicated_grid:
          type: boolean
          title: Whether the deployment should target dedicated Grid hosts.
          description: 'When true, the deployment will be pinned to Grid hosts dedicated to the environment using this deployment target.


            Dedicated Grid hosts must be created prior to deploying the environment.


            The constraints that will be set are as follows:


            * `cluster_type` is set to `environment-custom`.

            * `cluster` is set to the environment''s cluster name.'
        storage_type:
          type:
          - string
          - 'null'
          title: Storage Type
          description: The storage type
      required:
      - type
      - name
      - hosts
      - use_dedicated_grid
      - storage_type
      additionalProperties: false
    DeploymentTargetPatch:
      oneOf:
      - $ref: '#/components/schemas/DedicatedDeploymentTargetPatch'
      - $ref: '#/components/schemas/EnterpriseDeploymentTargetPatch'
      - $ref: '#/components/schemas/FoundationDeploymentTargetPatch'
      - $ref: '#/components/schemas/KubernetesDeploymentTargetStoragePatch'
    KubernetesDeploymentTargetStoragePatch:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
      required:
      - type
      - name
      additionalProperties: false
    EnterpriseDeploymentTargetCreateInput:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        site_urls:
          type: object
          title: Site URLs
          description: List of URLs of the site
        ssh_hosts:
          type: array
          items:
            type: string
          title: SSH Hosts
          description: List of SSH Hosts
        enterprise_environments_mapping:
          type: object
          title: Enterprise Environments Mapping
          description: Mapping of clusters to Enterprise applications
          deprecated: true
          x-stability: DEPRECATED
      required:
      - type
      - name
      additionalProperties: false
    FoundationDeploymentTargetCreateInput:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        hosts:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              id:
                type:
                - string
                - 'null'
                title: Host identifier
                description: The identifier of the host.
              type:
                type: string
                enum:
                - core
                - satellite
                title: Deployment type
                description: The type of the deployment to this host.
              services:
                type:
                - array
                - 'null'
                items:
                  type: string
                title: Assigned services
                description: The services assigned to this host
            required:
            - id
            - type
            additionalProperties: false
          title: Deployment hosts
          description: The hosts of the deployment target
        use_dedicated_grid:
          type: boolean
          title: Whether the deployment should target dedicated Grid hosts.
          description: 'When true, the deployment will be pinned to Grid hosts dedicated to the environment using this deployment target.


            Dedicated Grid hosts must be created prior to deploying the environment.


            The constraints that will be set are as follows:


            * `cluster_type` is set to `environment-custom`.

            * `cluster` is set to the environment''s cluster name.'
      required:
      - type
      - name
      additionalProperties: false
    FoundationDeploymentTargetPatch:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        hosts:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              id:
                type:
                - string
                - 'null'
                title: Host identifier
                description: The identifier of the host.
              type:
                type: string
                enum:
                - core
                - satellite
                title: Deployment type
                description: The type of the deployment to this host.
              services:
                type:
                - array
                - 'null'
                items:
                  type: string
                title: Assigned services
                description: The services assigned to this host
            required:
            - id
            - type
            additionalProperties: false
          title: Deployment hosts
          description: The hosts of the deployment target
        use_dedicated_grid:
          type: boolean
          title: Whether the deployment should target dedicated Grid hosts.
          description: 'When true, the deployment will be pinned to Grid hosts dedicated to the environment using this deployment target.


            Dedicated Grid hosts must be created prior to deploying the environment.


            The constraints that will be set are as follows:


            * `cluster_type` is set to `environment-custom`.

            * `cluster` is set to the environment''s cluster name.'
      required:
      - type
      - name
      additionalProperties: false
    DeploymentTarget:
      oneOf:
      - $ref: '#/components/schemas/DedicatedDeploymentTarget'
      - $ref: '#/components/schemas/EnterpriseDeploymentTarget'
      - $ref: '#/components/schemas/FoundationDeploymentTarget'
      - $ref: '#/components/schemas/KubernetesDeploymentTargetStorage'
    DeploymentTargetCollection:
      type: array
      items:
        $ref: '#/components/schemas/DeploymentTarget'
    KubernetesDeploymentTargetStorage:
      type: object
      properties:
        id:
          type: string
          title: KubernetesDeploymentTargetStorage Identifier
          description: The identifier of KubernetesDeploymentTargetStorage
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        k8s_config:
          type:
          - string
          - 'null'
          title: K8S config
          description: K8S config
        bastion_nodes_user:
          type:
          - string
          - 'null'
          title: The bastion-nodes ssh user
          description: The bastion-nodes ssh user
        bastion_nodes_host:
          type:
          - string
          - 'null'
          title: The bastion node endpoint
          description: The bastion node endpoint
      required:
      - type
      - name
      - k8s_config
      - bastion_nodes_user
      - bastion_nodes_host
      additionalProperties: false
    EnterpriseDeploymentTargetPatch:
      type: object
      properties:
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        site_urls:
          type: object
          title: Site URLs
          description: List of URLs of the site
        ssh_hosts:
          type: array
          items:
            type: string
          title: SSH Hosts
          description: List of SSH Hosts
        enterprise_environments_mapping:
          type: object
          title: Enterprise Environments Mapping
          description: Mapping of clusters to Enterprise applications
          deprecated: true
          x-stability: DEPRECATED
      required:
      - type
      - name
      additionalProperties: false
    EnterpriseDeploymentTarget:
      type: object
      properties:
        id:
          type: string
          title: EnterpriseDeploymentTarget Identifier
          description: The identifier of EnterpriseDeploymentTarget
        type:
          type: string
          enum:
          - dedicated
          - enterprise
          - foundation
          - kubernetes
          title: Deployment target type
          description: The type of the deployment target
        name:
          type: string
          title: Deployment target name
          description: The name of the deployment target
        deploy_host:
          type:
          - string
          - 'null'
          title: Deploy Host
          description: The host to deploy to
        docroots:
          type: object
          additionalProperties:
            type: object
            properties:
              active_docroot:
                type:
                - string
                - 'null'
                title: Active docroot
                description: The enterprise docroot, that is associated with this application/cluster.
              docroot_versions:
                type:
                - array
                - 'null'
                items:
                  type: string
                title: Docroot versions
                description: Versions of the enterprise docroot. When a new environment version is created the active_docroot is updated from these values.
            required:
            - active_docroot
            - docroot_versions
            additionalProperties: false
          title: Docroots
          description: Mapping of clusters to Enterprise applications
        site_urls:
          type: object
          title: Site URLs
          description: List of URLs of the site
        ssh_hosts:
          type: array
          items:
            type: string
          title: SSH Hosts
          description: List of SSH Hosts
        maintenance_mode:
          type: boolean
          title: Maintenance Mode
          description: Whether to perform deployments or not
        enterprise_environments_mapping:
          type: object
          title: Enterprise Environments Mapping
          description: Mapping of clusters to Enterprise applications
          deprecated: true
          x-stability: DEPRECATED
      required:
      - type
      - name
      - deploy_host
      - docroots
      - site_urls
      - ssh_hosts
      - maintenance_mode
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Organization Administration
  tags:
  - Organizations
  - Organization Members
  - Organization Invitations
  - Organization Projects
  - Add-ons
- name: Project Administration
  tags:
  - Project
  - Domain Claim
  - Domain Management
  - Cert Management
  - Certificate Provisioner
  - Project Variables
  - Repository
  - Third-Party Integrations
  - Support
- name: Environments
  tags:
  - Environment
  - Environment Backups
  - Environment Type
  - Environment Variables
  - Routing
  - Source Operations
  - Runtime Operations
  - Deployment
  - Autoscaling
  - Task
- name: User Activity
  tags:
  - Project Activity
  - Environment Activity
- name: Project Access
  tags:
  - Project Invitations
  - Teams
  - Team Access
  - User Access
- name: Account Management
  tags:
  - API Tokens
  - Connections
  - MFA
  - Users
  - User Profiles
  - SSH Keys
  - Plans
- name: Billing
  tags:
  - Organization Management
  - Subscriptions
  - Orders
  - Invoices
  - Discounts
  - Vouchers
  - Records
  - Profiles
  - Billing Profile Projects
- name: Global Info
  tags:
  - Project Discovery
  - References
  - Regions
- name: Observability
  tags:
  - Blackfire Profiling
  - Blackfire Monitoring
  - Resources
  - Http Traffic
  - Continuous Profiling
- name: Internal APIs
  tags:
  - Project Settings
  - Environment Settings
  - Deployment Target
  - System Information
  - Container Profile