Upsun Routing API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Routing 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:
- OAuth2: []
tags:
- name: Routing
  description: 'These endpoints modify an environment''s `routes:` section of the `.upsun/config.yaml` file.

    For routes to propagate to child environments, the child environments

    must be synchronized with their parent.


    More information about routing can be found in the [Routes](https://docs.upsun.com/anchors/routes/)

    section of the documentation.

    '
paths:
  /projects/{projectId}/environments/{environmentId}/routes:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      operationId: list-projects-environments-routes
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteCollection'
      tags:
      - Routing
      summary: Get list of routes
      description: 'Retrieve a list of objects containing route definitions for

        a specific environment. The definitions returned by this endpoint

        are those present in an environment''s `.upsun/config.yaml` file.

        '
  /projects/{projectId}/environments/{environmentId}/routes/{routeId}:
    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: routeId
      operationId: get-projects-environments-routes
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
      tags:
      - Routing
      summary: Get a route's info
      description: 'Get details of a route from an environment using the `id` of the entry

        retrieved by the [Get environment routes list](#tag/Environment-Routes%2Fpaths%2F~1projects~1%7BprojectId%7D~1environments~1%7BenvironmentId%7D~1routes%2Fget)

        endpoint.

        '
components:
  schemas:
    RedirectRoute:
      type: object
      properties:
        id:
          type: string
          title: RedirectRoute Identifier
          description: The identifier of RedirectRoute
        primary:
          type: boolean
          nullable: true
          title: Is primary
          description: This route is the primary route of the environment
        production_url:
          type: string
          nullable: true
          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
                  nullable: true
                  title: Is enabled
                  description: Whether strict transport security is enabled or not.
                include_subdomains:
                  type: boolean
                  nullable: true
                  title: Is subdomains included
                  description: Whether the strict transport security policy should include all subdomains.
                preload:
                  type: boolean
                  nullable: true
                  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
              enum:
              - TLSv1.0
              - TLSv1.1
              - TLSv1.2
              - TLSv1.3
              nullable: true
              title: Minimum TLS version
              description: The minimum TLS version to support.
            client_authentication:
              type: string
              enum:
              - request
              - require
              nullable: true
              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: ''
        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
                    nullable: true
                    title: Is prefix
                    description: Whether to redirect all the paths that start with the path.
                  append_suffix:
                    type: boolean
                    nullable: true
                    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
                    nullable: true
                    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
    RouteCollection:
      type: array
      items:
        $ref: '#/components/schemas/Route'
    Route:
      oneOf:
      - $ref: '#/components/schemas/ProxyRoute'
      - $ref: '#/components/schemas/RedirectRoute'
      - $ref: '#/components/schemas/UpstreamRoute'
    UpstreamRoute:
      type: object
      properties:
        id:
          type: string
          title: UpstreamRoute Identifier
          description: The identifier of UpstreamRoute
        primary:
          type: boolean
          nullable: true
          title: Is primary
          description: This route is the primary route of the environment
        production_url:
          type: string
          nullable: true
          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
                  nullable: true
                  title: Is enabled
                  description: Whether strict transport security is enabled or not.
                include_subdomains:
                  type: boolean
                  nullable: true
                  title: Is subdomains included
                  description: Whether the strict transport security policy should include all subdomains.
                preload:
                  type: boolean
                  nullable: true
                  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
              enum:
              - TLSv1.0
              - TLSv1.1
              - TLSv1.2
              - TLSv1.3
              nullable: true
              title: Minimum TLS version
              description: The minimum TLS version to support.
            client_authentication:
              type: string
              enum:
              - request
              - require
              nullable: true
              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.
        cache:
          type: object
          properties:
            enabled:
              type: boolean
              title: Is enabled
              description: Whether the cache is enabled.
            default_ttl:
              type: integer
              title: Default TTL
              description: The TTL to apply when the response doesn't specify one. Only applies to static files.
            cookies:
              type: array
              items:
                type: string
              title: Cookies
              description: The cookies to take into account for the cache key.
            headers:
              type: array
              items:
                type: string
              title: Headers
              description: The headers to take into account for the cache key.
          required:
          - enabled
          - default_ttl
          - cookies
          - headers
          additionalProperties: false
          title: Cache configuration
          description: Cache configuration.
        ssi:
          type: object
          properties:
            enabled:
              type: boolean
              title: Is enabled
              description: Whether SSI include is enabled.
          required:
          - enabled
          additionalProperties: false
          title: SSI configuration
          description: Server-Side Include configuration.
        upstream:
          type: string
          title: Upstream
          description: The upstream to use for this route.
        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
                    nullable: true
                    title: Is prefix
                    description: Whether to redirect all the paths that start with the path.
                  append_suffix:
                    type: boolean
                    nullable: true
                    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
                    nullable: true
                    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.
        sticky:
          type: object
          properties:
            enabled:
              type: boolean
              title: Is enabled
              description: Whether sticky routing is enabled.
          required:
          - enabled
          additionalProperties: false
          title: Sticky configuration
          description: Sticky routing configuration.
      required:
      - primary
      - id
      - production_url
      - attributes
      - type
      - tls
      - cache
      - ssi
      - upstream
      - redirects
      - sticky
      additionalProperties: false
    ProxyRoute:
      type: object
      properties:
        id:
          type: string
          title: ProxyRoute Identifier
          description: The identifier of ProxyRoute
        primary:
          type: boolean
          nullable: true
          title: Is primary
          description: This route is the primary route of the environment
        production_url:
          type: string
          nullable: true
          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
                  nullable: true
                  title: Is enabled
                  description: Whether strict transport security is enabled or not.
                include_subdomains:
                  type: boolean
                  nullable: true
                  title: Is subdomains included
                  description: Whether the strict transport security policy should include all subdomains.
                preload:
                  type: boolean
                  nullable: true
                  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
              enum:
              - TLSv1.0
              - TLSv1.1
              - TLSv1.2
              - TLSv1.3
              nullable: true
              title: Minimum TLS version
              description: The minimum TLS version to support.
            client_authentication:
              type: string
              enum:
              - request
              - require
              nullable: true
              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: ''
      required:
      - primary
      - id
      - production_url
      - attributes
      - type
      - tls
      - to
      additionalProperties: false
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: https://auth.api.platform.sh/oauth2/token
          scopes: {}
          authorizationUrl: https://auth.api.platform.sh/oauth2/authorize
      description: ''
    OAuth2Admin:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: ''
          scopes:
            admin: administrative operations
      description: ''
x-tagGroups:
- name: Organization Administration
  tags:
  - Organizations
  - Organization Members
  - Organization Invitations
  - Organization Projects
  - Add-ons
- name: Project Administration
  tags:
  - Project
  - 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
- 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
- name: Global Info
  tags:
  - Project Discovery
  - References
  - Regions
- name: Internal APIs
  tags:
  - Project Settings
  - Environment Settings
  - Deployment Target
  - System Information
  - Container Profile