Upsun Organization Management API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Organization Management 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: Organization Management
paths:
  /organizations/{organization_id}/estimate:
    get:
      summary: Estimate total spend
      description: Estimates the total spend for the specified organization.
      operationId: estimate-org
      tags:
      - Organization Management
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEstimationObject'
        '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'
      x-vendor: upsun
  /organizations/{organization_id}/alerts/billing:
    get:
      summary: Get billing alert configuration
      description: Retrieves billing alert configuration for the specified organization.
      operationId: get-org-billing-alert-config
      tags:
      - Organization Management
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationAlertConfig'
        '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'
      x-vendor: upsun
    patch:
      summary: Update billing alert configuration
      description: Updates billing alert configuration for the specified organization.
      operationId: update-org-billing-alert-config
      tags:
      - Organization Management
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                active:
                  type: boolean
                  description: Whether the billing alert should be active or not.
                config:
                  type: object
                  description: The configuration for billing alerts.
                  properties:
                    threshold:
                      type: integer
                      description: The amount after which a billing alert should be triggered.
                    mode:
                      type: string
                      description: The mode in which the alert is triggered.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationAlertConfig'
        '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'
      x-vendor: upsun
  /organizations/{organization_id}/prepayment:
    get:
      summary: Get organization prepayment information
      description: Retrieves prepayment information for the specified organization, if applicable.
      operationId: get-org-prepayment-info
      tags:
      - Organization Management
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  prepayment:
                    $ref: '#/components/schemas/PrepaymentObject'
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        description: Link to the current resource.
                        properties:
                          href:
                            type: string
                            description: URL of the link.
                      transactions:
                        type: object
                        description: Link to the prepayment transactions resource.
                        properties:
                          href:
                            type: string
                            description: URL of the link.
        '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'
      x-vendor: upsun
  /organizations/{organization_id}/prepayment/transactions:
    get:
      summary: List organization prepayment transactions
      description: Retrieves a list of prepayment transactions for the specified organization, if applicable.
      operationId: list-org-prepayment-transactions
      tags:
      - Organization Management
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of items across pages.
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PrepaymentTransactionObject'
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        description: Link to the current set of items.
                        properties:
                          href:
                            type: string
                            description: URL of the link.
                      previous:
                        type: object
                        description: Link to the previous set of items.
                        properties:
                          href:
                            type: string
                            description: URL of the link.
                      next:
                        type: object
                        description: Link to the next set of items.
                        properties:
                          href:
                            type: string
                            description: URL of the link
                      prepayment:
                        type: object
                        description: Link to the prepayment resource.
                        properties:
                          href:
                            type: string
                            description: URL of the link.
        '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'
      x-vendor: upsun
components:
  schemas:
    OrganizationEstimationObject:
      type: object
      description: An estimation of all organization spend.
      properties:
        total:
          type: string
          description: The total estimated price for the organization.
        sub_total:
          type: string
          description: The sub total for all projects and sellables.
        vouchers:
          type: string
          description: The total amount of vouchers.
        user_licenses:
          type: object
          description: An estimation of user licenses cost.
          properties:
            base:
              type: object
              properties:
                count:
                  type: integer
                  description: The number of base user licenses.
                total:
                  type: string
                  description: The total price for base user licenses.
                list:
                  type: object
                  properties:
                    admin_user:
                      type: object
                      description: An estimation of admin users cost.
                      properties:
                        count:
                          type: integer
                          description: The number of admin user licenses.
                        total:
                          type: string
                          description: The total price for admin user licenses.
                    viewer_user:
                      type: object
                      description: An estimation of viewer users cost.
                      properties:
                        count:
                          type: integer
                          description: The number of viewer user licenses.
                        total:
                          type: string
                          description: The total price for viewer user licenses.
            user_management:
              type: object
              properties:
                count:
                  type: integer
                  description: The number of user_management licenses.
                total:
                  type: string
                  description: The total price for user_management licenses.
                list:
                  type: object
                  properties:
                    standard_management_user:
                      type: object
                      description: An estimation of standard_management_user cost.
                      properties:
                        count:
                          type: integer
                          description: The number of standard_management_user licenses.
                        total:
                          type: string
                          description: The total price for standard_management_user licenses.
                    advanced_management_user:
                      type: object
                      description: An estimation of advanced_management_user cost.
                      properties:
                        count:
                          type: integer
                          description: The number of advanced_management_user licenses.
                        total:
                          type: string
                          description: The total price for advanced_management_user licenses.
        user_management:
          type: string
          description: An estimation of the advanced user management sellable cost.
        support_level:
          type: string
          description: The total monthly price for premium support.
        subscriptions:
          type: object
          description: An estimation of subscriptions cost.
          properties:
            total:
              type: string
              description: The total price for subscriptions.
            list:
              type: array
              description: The list of active subscriptions.
              items:
                description: Details of a subscription
                type: object
                properties:
                  license_id:
                    type: string
                    description: The id of the subscription.
                  project_title:
                    type: string
                    description: The name of the project.
                  total:
                    type: string
                    description: The total price for the subscription.
                  usage:
                    type: object
                    description: The detail of the usage for the subscription.
                    properties:
                      cpu:
                        type: number
                        description: The total cpu for this subsciption.
                      memory:
                        type: number
                        description: The total memory for this subsciption.
                      storage:
                        type: number
                        description: The total storage for this subsciption.
                      environments:
                        type: integer
                        description: The total environments for this subsciption.
    PrepaymentObject:
      type: object
      description: Prepayment information for an organization.
      properties:
        prepayment:
          type: object
          description: Prepayment information for an organization.
          properties:
            organization_id:
              type: string
              description: Organization ID
            balance:
              type: object
              description: The prepayment balance in complex format.
              properties:
                formatted:
                  type: string
                  description: Formatted balance.
                amount:
                  type: number
                  description: The balance amount.
                currency_code:
                  type: string
                  description: The balance currency code.
                currency_symbol:
                  type: string
                  description: The balance currency symbol.
            last_updated_at:
              type: string
              nullable: true
              description: The date the prepayment balance was last updated.
            sufficient:
              type: boolean
              description: Whether the prepayment balance is enough to cover the upcoming order.
            fallback:
              type: string
              nullable: true
              description: The fallback payment method, if any, to be used in case prepayment balance is not enough to cover an order.
    Error:
      description: ''
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        code:
          type: number
        detail:
          type: object
        title:
          type: string
      title: ''
      x-examples:
        example-1:
          status: Invalid input
          message: This field is required.
          code: 400
          detail:
            field:
            - This field is required.
          title: Bad Request
    PrepaymentTransactionObject:
      type: object
      description: Prepayment transaction for an organization.
      properties:
        order_id:
          type: string
          description: Order ID
        message:
          type: string
          description: The message associated with transaction.
        status:
          type: string
          description: Whether the transactions was successful or a failure.
        amount:
          type: object
          description: The prepayment balance in complex format.
          properties:
            formatted:
              type: string
              description: Formatted balance.
            amount:
              type: number
              description: The balance amount.
            currency_code:
              type: string
              description: The balance currency code.
            currency_symbol:
              type: string
              description: The balance currency symbol.
        created:
          type: string
          description: Time the transaction was created.
        updated:
          type: string
          description: Time the transaction was last updated.
          nullable: true
        expire_date:
          type: string
          description: The expiration date of the transaction (deposits only).
          nullable: true
    OrganizationAlertConfig:
      type: object
      description: The alert configuration for an organization.
      properties:
        id:
          type: string
          description: Type of alert (e.g. "billing")
        active:
          type: boolean
          description: Whether the billing alert should be active or not.
        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 threshold and mode.
          properties:
            threshold:
              type: object
              description: Data regarding threshold spend.
              properties:
                formatted:
                  type: string
                  description: Formatted threshold value.
                amount:
                  type: number
                  description: Threshold value.
                currency_code:
                  type: string
                  description: Threshold currency code.
                currency_symbol:
                  type: string
                  description: Threshold currency symbol.
            mode:
              type: string
              description: The mode of alert.
  parameters:
    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
  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