Upsun Subscriptions API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Subscriptions 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: Subscriptions
  description: 'Each project is represented by a subscription that holds the plan information.

    These endpoints can be used to go to a larger plan, add more storage, or subscribe to

    optional features.

    '
paths:
  /subscriptions/{subscriptionId}/can-update:
    get:
      tags:
      - Subscriptions
      summary: Checks if the user is able to update a project.
      operationId: can-update-subscription
      parameters:
      - $ref: '#/components/parameters/subscription_id'
      - $ref: '#/components/parameters/subscription_plan'
      - $ref: '#/components/parameters/subscription_environments'
      - $ref: '#/components/parameters/subscription_storage'
      - $ref: '#/components/parameters/subscription_user_licenses'
      responses:
        '200':
          description: Check result with error message if presented
          content:
            application/json:
              schema:
                properties:
                  can_update:
                    description: Boolean result of the check.
                    type: boolean
                  message:
                    description: Details in case of negative check result.
                    type: string
                  required_action:
                    description: Required action impeding project update.
                    type: object
                type: object
  /organizations/{organization_id}/subscriptions/estimate:
    get:
      summary: Estimate the price of a new subscription
      operationId: estimate-new-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - in: query
        name: plan
        description: The plan type of the subscription.
        required: true
        schema:
          type: string
      - in: query
        name: environments
        description: The maximum number of environments which can be provisioned on the project.
        required: true
        schema:
          type: integer
      - in: query
        name: storage
        description: The total storage available to each environment, in MiB.
        required: true
        schema:
          type: integer
      - in: query
        name: user_licenses
        description: The number of user licenses.
        required: true
        schema:
          type: integer
      - in: query
        name: format
        description: The format of the estimation output.
        required: false
        schema:
          type: string
          enum:
          - formatted
          - complex
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimationObject'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions/can-create:
    get:
      summary: Checks if the user is able to create a new project.
      operationId: can-create-new-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  can_create:
                    description: Boolean result of the check.
                    type: boolean
                  message:
                    description: Details in case of negative check result.
                    type: string
                  required_action:
                    description: Required action impending project creation.
                    type: object
                    nullable: true
                    properties:
                      action:
                        description: Machine readable definition of requirement.
                        type: string
                      type:
                        description: Specification of the type of action.
                        type: string
                type: object
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions/{subscription_id}/estimate:
    get:
      summary: Estimate the price of a subscription
      operationId: estimate-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      - in: query
        name: plan
        description: The plan type of the subscription.
        required: true
        schema:
          type: string
      - in: query
        name: environments
        description: The maximum number of environments which can be provisioned on the project.
        schema:
          type: integer
      - in: query
        name: storage
        description: The total storage available to each environment, in MiB.
        schema:
          type: integer
      - in: query
        name: user_licenses
        description: The number of user licenses.
        schema:
          type: integer
      - in: query
        name: format
        description: The format of the estimation output.
        schema:
          type: string
          enum:
          - formatted
          - complex
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimationObject'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions/{subscription_id}/current_usage:
    get:
      summary: Get current usage for a subscription
      operationId: get-org-subscription-current-usage
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      - in: query
        name: usage_groups
        description: A list of usage groups to retrieve current usage for.
        schema:
          type: string
      - in: query
        name: include_not_charged
        description: Whether to include not charged usage groups.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCurrentUsageObject'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions/{subscription_id}/addons:
    get:
      summary: List addons for a subscription
      operationId: list-subscription-addons
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAddonsObject'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      x-vendor: upsun
  /organizations/{organization_id}/alerts/subscriptions/{subscription_id}/usage:
    get:
      summary: Get usage alerts
      description: Retrieves current and available usage alerts.
      operationId: get-subscription-usage-alerts
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      - $ref: '#/components/parameters/SubscriptionID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: array
                    description: The list of currently set usage alerts.
                    items:
                      $ref: '#/components/schemas/UsageAlert'
                  available:
                    type: array
                    description: The list of available usage alerts.
                    items:
                      $ref: '#/components/schemas/UsageAlert'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Update usage alerts.
      description: Updates usage alerts for a subscription.
      operationId: update-subscription-usage-alerts
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      - $ref: '#/components/parameters/SubscriptionID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                alerts:
                  type: array
                  description: The list of alerts to update.
                  items:
                    type: object
                    description: An alert object.
                    properties:
                      id:
                        type: string
                        description: The usage alert identifier.
                      active:
                        type: boolean
                        description: Whether the alert is activated.
                      config:
                        type: object
                        description: The configuration for the usage alerts.
                        properties:
                          threshold:
                            type: integer
                            description: The amount after which an alert should be triggered.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: array
                    description: The list of currently set usage alerts.
                    items:
                      $ref: '#/components/schemas/UsageAlert'
                  available:
                    type: array
                    description: The list of available usage alerts.
                    items:
                      $ref: '#/components/schemas/UsageAlert'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions:
    get:
      summary: List subscriptions
      description: Retrieves subscriptions for the specified organization.
      operationId: list-org-subscriptions
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/subscription_status'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/project_title'
      - $ref: '#/components/parameters/region'
      - $ref: '#/components/parameters/updated_at'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/page_before'
      - $ref: '#/components/parameters/page_after'
      - $ref: '#/components/parameters/subscription_sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  _links:
                    $ref: '#/components/schemas/ListLinks'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create subscription
      description: Creates a subscription for the specified organization.
      operationId: create-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_region
              properties:
                plan:
                  $ref: '#/components/schemas/ProjectPlan'
                project_region:
                  type: string
                  description: The machine name of the region where the project is located. Cannot be changed after project creation.
                project_title:
                  type: string
                  description: The name given to the project. Appears as the title in the UI.
                options_url:
                  type: string
                  description: The URL of the project options file.
                default_branch:
                  type: string
                  description: The default Git branch name for the project.
                environments:
                  type: integer
                  description: The maximum number of active environments on the project.
                storage:
                  type: integer
                  description: The total storage available to each environment, in MiB. Only multiples of 1024 are accepted as legal values.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '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'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/subscriptions/{subscription_id}:
    get:
      summary: Get subscription
      description: Retrieves a subscription for the specified organization.
      operationId: get-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Update subscription
      description: Updates a subscription for the specified organization.
      operationId: update-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project_title:
                  $ref: '#/components/schemas/ProjectTitle'
                plan:
                  $ref: '#/components/schemas/ProjectPlan'
                timezone:
                  $ref: '#/components/schemas/ProjectTimeZone'
                environments:
                  type: integer
                  description: The maximum number of environments which can be provisioned on the project.
                storage:
                  type: integer
                  description: The total storage available to each environment, in MiB.
                big_dev:
                  type: string
                  description: The development environment plan.
                big_dev_service:
                  type: string
                  description: The development service plan.
                backups:
                  type: string
                  description: The backups plan.
                observability_suite:
                  type: string
                  description: The observability suite option.
                blackfire:
                  type: string
                  description: The Blackfire integration option.
                continuous_profiling:
                  type: string
                  description: The Blackfire continuous profiling option.
                project_support_level:
                  type: string
                  description: The project uptime option.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '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'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete subscription
      description: Deletes a subscription for the specified organization.
      operationId: delete-org-subscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/SubscriptionID'
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    subscription_status:
      name: filter[status]
      in: query
      description: 'The status of the subscription. '
      schema:
        type: string
        enum:
        - active
        - provisioning
        - provisioning failure
        - suspended
        - deleted
    subscription_environments:
      name: environments
      in: query
      description: The number of environments which can be provisioned on the project.
      schema:
        type: integer
        default: null
    project_id:
      name: filter[project_id]
      in: query
      description: Allows filtering by `project_id` using one or more operators.
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/StringFilter'
    subscription_storage:
      name: storage
      in: query
      description: The total storage available to each environment, in MiB. Only multiples of 1024 are accepted as legal values.
      schema:
        type: integer
        default: null
    page_before:
      in: query
      name: page[before]
      description: Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.
      schema:
        type: string
    OrganizationIDName:
      in: path
      name: organization_id
      description: 'The ID of the organization.<br>

        Prefix with name= to retrieve the organization by name instead.

        '
      required: true
      schema:
        type: string
    OrganizationID:
      name: organization_id
      in: path
      required: true
      description: The ID of the organization.
      schema:
        type: string
        format: ulid
    project_title:
      in: query
      name: filter[project_title]
      description: Allows filtering by `project_title` using one or more operators.
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/StringFilter'
    page_size:
      in: query
      name: page[size]
      description: Determines the number of items to show.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: null
    updated_at:
      in: query
      name: filter[updated_at]
      description: Allows filtering by `updated_at` using one or more operators.
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/DateTimeFilter'
    region:
      in: query
      name: filter[region]
      description: Allows filtering by `region` using one or more operators.
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/StringFilter'
    subscription_user_licenses:
      name: user_licenses
      in: query
      description: The number of user licenses.
      schema:
        type: integer
    page_after:
      in: query
      name: page[after]
      description: Pagination cursor. This is automatically generated as necessary and provided in HAL links (_links); it should not be constructed externally.
      schema:
        type: string
    id:
      name: filter[id]
      in: query
      description: Machine name of the region.
      schema:
        type: string
    subscription_sort:
      in: query
      name: sort
      description: 'Allows sorting by a single field.<br>

        Use a dash ("-") to sort descending.<br>

        Supported fields: `region`, `project_title`, `type`, `plan`, `status`, `created_at`, `updated_at`.

        '
      schema:
        type: string
        example: -updated_at
    subscription_id:
      name: subscriptionId
      in: path
      description: The ID of the subscription
      required: true
      schema:
        type: string
    subscription_plan:
      name: plan
      in: query
      description: The plan type of the subscription.
      schema:
        type: string
        enum:
        - development
        - standard
        - medium
        - large
        - xlarge
        - 2xlarge
    SubscriptionID:
      in: path
      name: subscription_id
      description: The ID of the subscription.
      required: true
      schema:
        type: string
  schemas:
    ProjectTimeZone:
      type: string
      description: Timezone of the project.
    UsageAlert:
      type: object
      description: The usage alert for a subscription.
      properties:
        id:
          type: string
          description: Tidentifier of the alert.
        active:
          type: boolean
          description: Whether the usage alert is activated.
        alerts_sent:
          type: number
          description: Number of alerts sent.
        last_alert_at:
          type: string
          description: The datetime the alert was last sent.
          nullable: true
        updated_at:
          type: string
          description: The datetime the alert was last updated.
          nullable: true
        config:
          type: object
          nullable: true
          description: Configuration for the usage alert.
          properties:
            threshold:
              type: object
              description: Data regarding threshold spend.
              properties:
                formatted:
                  type: string
                  description: Formatted threshold value.
                amount:
                  type: number
                  description: Threshold value.
                unit:
                  type: string
                  description: Threshold unit.
    OwnerInfo:
      description: Project owner information that can be exposed to collaborators.
      properties:
        type:
          description: Type of the owner, usually 'u

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upsun/refs/heads/main/openapi/upsun-subscriptions-api-openapi.yml