Platform.sh References API

openapi: 3.2.0
info:
  title: Upsun.com Rest References 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: References
paths:
  /ref/users:
    get:
      summary: List referenced users
      description: Retrieves a list of users referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:users:0</code>.
      operationId: list-referenced-users
      tags:
      - References
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A map of referenced users indexed by the user ID.
                additionalProperties:
                  $ref: '#/components/schemas/UserReference'
              examples:
                example-1:
                  value:
                    497f6eca-6276-4993-bfeb-53cbbbba6f08:
                      email: user@example.com
                      first_name: string
                      id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                      last_name: string
                      picture: https://accounts.platform.sh/profiles/blimp_profile/themes/platformsh_theme/images/mail/logo.png
                      username: string
                      mfa_enabled: false
                      sso_enabled: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - schema:
          type: string
        in: query
        name: in
        description: The list of comma-separated user IDs generated by a trusted service.
        required: true
      - schema:
          type: string
        in: query
        name: sig
        description: The signature of this request generated by a trusted service.
        required: true
  /ref/teams:
    get:
      summary: List referenced teams
      description: Retrieves a list of teams referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:teams:0</code>.
      operationId: list-referenced-teams
      tags:
      - References
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A map of referenced teams indexed by the team ID.
                additionalProperties:
                  $ref: '#/components/schemas/TeamReference'
              examples:
                example-1:
                  value:
                    01FVMKN9KHVWWVY488AVKDWHR3:
                      id: 01FVMKN9KHVWWVY488AVKDWHR3
                      label: Contractors
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - schema:
          type: string
        in: query
        name: in
        description: The list of comma-separated team IDs generated by a trusted service.
        required: true
      - schema:
          type: string
        in: query
        name: sig
        description: The signature of this request generated by a trusted service.
        required: true
  /ref/organizations:
    get:
      summary: List referenced organizations
      description: Retrieves a list of organizations referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:organizations:0</code>.
      operationId: list-referenced-orgs
      tags:
      - References
      parameters:
      - schema:
          type: string
        in: query
        name: in
        description: The list of comma-separated organization IDs generated by a trusted service.
        required: true
      - schema:
          type: string
        in: query
        name: sig
        description: The signature of this request generated by a trusted service.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A map of referenced organizations indexed by the organization ID.
                additionalProperties:
                  $ref: '#/components/schemas/OrganizationReference'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /ref/projects:
    get:
      summary: List referenced projects
      description: Retrieves a list of projects referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:projects:0</code>.
      operationId: list-referenced-projects
      tags:
      - References
      parameters:
      - schema:
          type: string
        in: query
        name: in
        description: The list of comma-separated project IDs generated by a trusted service.
        required: true
      - schema:
          type: string
        in: query
        name: sig
        description: The signature of this request generated by a trusted service.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A map of referenced projects indexed by the organization ID.
                additionalProperties:
                  $ref: '#/components/schemas/ProjectReference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /ref/regions:
    get:
      summary: List referenced regions
      description: Retrieves a list of regions referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of another API response, in the <code>_links</code> object with a key like <code>ref:regions:0</code>.
      operationId: list-referenced-regions
      tags:
      - References
      parameters:
      - schema:
          type: string
        in: query
        name: in
        description: The list of comma-separated region IDs generated by a trusted service.
        required: true
      - schema:
          type: string
        in: query
        name: sig
        description: The signature of this request generated by a trusted service.
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A map of referenced projects indexed by the organization ID.
                additionalProperties:
                  $ref: '#/components/schemas/RegionReference'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RegionEndpoint:
      type: string
      description: Link to the region API endpoint.
    ProjectType:
      type: string
      description: The type of projects.
      enum:
      - grid
      - dedicated
    RegionTimezone:
      type: string
      description: Default timezone of the region.
    TeamReference:
      description: The referenced team, or null if it no longer exists.
      type: object
      properties:
        id:
          type: string
          format: ulid
          description: The ID of the team.
        organization_id:
          type: string
          format: ulid
          description: The ID of the parent organization.
        label:
          type: string
          description: The human-readable label of the team.
        project_permissions:
          type: array
          description: Project permissions that are granted to the team.
          items:
            type: string
            enum:
            - admin
            - viewer
            - development:admin
            - development:contributor
            - development:viewer
            - staging:admin
            - staging:contributor
            - staging:viewer
            - production:admin
            - production:contributor
            - production:viewer
        counts:
          type: object
          properties:
            member_count:
              type: integer
              description: Total count of members of the team.
            project_count:
              type: integer
              description: Total count of projects that the team has access to.
        created_at:
          type: string
          format: date-time
          description: The date and time when the team was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time when the team was last updated.
      x-examples:
        example-1:
          id: 01FVMKN9KHVWWVY488AVKDWHR3
          organization_id: 01EY8BWRSQ56EY1TDC32PARAJS
          counts:
            member_count: 12
            project_count: 5
          label: Contractors
          project_permissions:
          - viewer
          - staging:contributor
          - development:admin
          created_at: '2021-05-24T07:20:35.683264Z'
          updated_at: '2021-05-24T07:20:35.683264Z'
    RegionProjectLabel:
      type: string
      description: The label to display on existing projects.
    RegionZone:
      type: string
      description: The geographical zone of the region.
    ProjectReference:
      description: The referenced project, or null if it no longer exists.
      type:
      - object
      - 'null'
      required:
      - id
      - organization_id
      - subscription_id
      - region
      - title
      - type
      - plan
      - status
      - created_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/ProjectID'
        organization_id:
          $ref: '#/components/schemas/OrganizationID'
        subscription_id:
          $ref: '#/components/schemas/SubscriptionID'
        region:
          $ref: '#/components/schemas/RegionID'
        title:
          $ref: '#/components/schemas/ProjectTitle'
        type:
          $ref: '#/components/schemas/ProjectType'
        plan:
          $ref: '#/components/schemas/ProjectPlan'
        status:
          $ref: '#/components/schemas/ProjectStatus'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        invoiced:
          type: boolean
          description: Whether the project is invoiced.
      additionalProperties: false
    OrganizationReference:
      description: The referenced organization, or null if it no longer exists.
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
          format: ulid
          description: The ID of the organization.
        type:
          type: string
          description: The type of the organization.
        owner_id:
          type: string
          format: uuid
          description: The ID of the owner.
        name:
          type: string
          description: A unique machine name representing the organization.
        label:
          type: string
          description: The human-readable label of the organization.
        vendor:
          type: string
          description: The vendor.
        created_at:
          type: string
          format: date-time
          description: The date and time when the organization was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time when the organization was last updated.
    RegionCompliance:
      type: object
      description: Information about the region's compliance.
      properties:
        hipaa:
          type: boolean
          description: Indicator whether or not this region is HIPAA compliant.
      additionalProperties: false
    RegionDatacenter:
      type: object
      description: Information about the region provider data center.
      properties:
        name:
          type: string
          description: The name/identifier of the data center.
        label:
          type: string
          description: The human-readable label of the data center.
        location:
          type: string
          description: The physical location of the data center.
      additionalProperties: false
    RegionPrivate:
      type: boolean
      description: Indicator whether or not this platform is for private use only.
    CreatedAt:
      type: string
      format: date-time
      description: The date and time when the resource was created.
    RegionSelectionLabel:
      type: string
      description: The label to display when choosing between regions for new projects.
    UserReference:
      description: The referenced user, or null if it no longer exists.
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the user.
        username:
          type: string
          description: The user's username.
        email:
          type: string
          format: email
          description: The user's email address.
        first_name:
          type: string
          description: The user's first name.
        last_name:
          type: string
          description: The user's last name.
        picture:
          type: string
          format: uri
          description: The user's picture.
        mfa_enabled:
          type: boolean
          description: 'Whether the user has enabled MFA. Note: the built-in MFA feature may not be necessary if the user is linked to a mandatory SSO provider that itself supports MFA (see "sso_enabled\").'
        sso_enabled:
          type: boolean
          description: Whether the user is linked to a mandatory SSO provider.
      x-examples:
        example-1:
          email: hello@platform.sh
          first_name: Hello
          id: d81c8ee2-44b3-429f-b944-a33ad7437690
          last_name: World
          picture: https://accounts.platform.sh/profiles/blimp_profile/themes/platformsh_theme/images/mail/logo.png
          username: platform-sh
          mfa_enabled: true
          sso_enabled: true
    ProjectPlan:
      type: string
      description: The project plan.
    RegionEnvImpact:
      type: object
      description: Information about the region provider's environmental impact.
      properties:
        zone:
          type: string
          description: The geographical zone code for carbon intensity.
        carbon_intensity:
          type: number
          description: The carbon intensity value.
        carbon_intensity_source:
          type: string
          description: The source of the carbon intensity data.
        green:
          type: boolean
          description: Indicator whether the data center uses green energy.
      additionalProperties: false
    RegionReference:
      description: The referenced region, or null if it no longer exists.
      type:
      - object
      - 'null'
      required:
      - id
      - label
      - zone
      - selection_label
      - project_label
      - timezone
      - available
      - endpoint
      - provider
      - datacenter
      - compliance
      - created_at
      - updated_at
      properties:
        id:
          $ref: '#/components/schemas/RegionID'
        label:
          $ref: '#/components/schemas/RegionLabel'
        zone:
          $ref: '#/components/schemas/RegionZone'
        selection_label:
          $ref: '#/components/schemas/RegionSelectionLabel'
        project_label:
          $ref: '#/components/schemas/RegionProjectLabel'
        timezone:
          $ref: '#/components/schemas/RegionTimezone'
        available:
          $ref: '#/components/schemas/RegionAvailable'
        private:
          $ref: '#/components/schemas/RegionPrivate'
        endpoint:
          $ref: '#/components/schemas/RegionEndpoint'
        provider:
          $ref: '#/components/schemas/RegionProvider'
        datacenter:
          $ref: '#/components/schemas/RegionDatacenter'
        envimpact:
          $ref: '#/components/schemas/RegionEnvImpact'
        compliance:
          $ref: '#/components/schemas/RegionCompliance'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        environmental_impact:
          type: object
          description: Environmental impact information for the region.
      additionalProperties: false
    ProjectID:
      type: string
      description: The ID of the project.
    SubscriptionID:
      type: string
      description: The ID of the subscription.
    UpdatedAt:
      type: string
      format: date-time
      description: The date and time when the resource was last updated.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    RegionID:
      type: string
      description: The machine name of the region where the project is located.
    RegionProvider:
      type: object
      description: Information about the region provider.
      properties:
        name:
          type: string
          description: The name of the cloud provider.
        logo:
          type: string
          description: The logo of the cloud provider (base64 encoded SVG).
      additionalProperties: false
    RegionLabel:
      type: string
      description: The human-readable name of the region.
    OrganizationID:
      type: string
      description: The ID of the organization.
    RegionAvailable:
      type: boolean
      description: Indicator whether or not this region is selectable during the checkout. Not available regions will never show up during checkout.
    ProjectTitle:
      type: string
      description: The title of the project.
    ProjectStatus:
      type: string
      description: The status of the project.
      enum:
      - requested
      - active
      - failed
      - suspended
      - deleted
  responses:
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
  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