Upsun Organizations API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Organizations 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: Organizations
paths:
  /users/{user_id}/organizations:
    get:
      summary: User organizations
      description: Retrieves organizations that the specified user is a member of.
      operationId: list-user-orgs
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/UserID'
      - in: query
        name: filter[id]
        description: Allows filtering by `id` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[type]
        description: Allows filtering by `type` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[vendor]
        description: 'Allows filtering by `vendor` using one or more operators.

          '
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[status]
        description: 'Allows filtering by `status` using one or more operators.<br>

          Defaults to `filter[status][in]=active,restricted,suspended`.

          '
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - 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'
      - in: query
        name: page[size]
        description: Determines the number of items to show.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: null
      - 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
      - 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
      - in: query
        name: sort
        description: 'Allows sorting by a single field.<br>

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

          Supported fields: `name`, `label`, `created_at`, `updated_at`.

          '
        schema:
          type: string
          example: -updated_at
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  _links:
                    $ref: '#/components/schemas/ListLinks'
        '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'
  /organizations:
    get:
      summary: List organizations
      description: Non-admin users will only see organizations they are members of.
      operationId: list-orgs
      tags:
      - Organizations
      parameters:
      - in: query
        name: filter[id]
        description: Allows filtering by `id` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[type]
        description: 'Allows filtering by `type` using one or more operators.

          '
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[owner_id]
        description: Allows filtering by `owner_id` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[name]
        description: Allows filtering by `name` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[label]
        description: Allows filtering by `label` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[vendor]
        description: 'Allows filtering by `vendor` using one or more operators.

          '
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - in: query
        name: filter[capabilities]
        description: Allows filtering by `capabilites` using one or more operators.
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/ArrayFilter'
      - in: query
        name: filter[status]
        description: 'Allows filtering by `status` using one or more operators.<br>

          Defaults to `filter[status][in]=active,restricted,suspended`.

          '
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/StringFilter'
      - 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'
      - in: query
        name: page[size]
        description: Determines the number of items to show.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: null
      - 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
      - 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
      - in: query
        name: sort
        description: 'Allows sorting by a single field.<br>

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

          Supported fields: `name`, `label`, `created_at`, `updated_at`.

          '
        schema:
          type: string
          example: -updated_at
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of items across pages.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  _links:
                    $ref: '#/components/schemas/ListLinks'
        '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'
    post:
      summary: Create organization
      description: Creates a new organization.
      operationId: create-org
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - label
              properties:
                type:
                  type: string
                  description: The type of the organization.
                  enum:
                  - fixed
                  - flexible
                owner_id:
                  type: string
                  format: uuid
                  description: 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.
                country:
                  type: string
                  description: The organization country (2-letter country code).
                  maxLength: 2
                security_contact:
                  type: string
                  format: email
                  description: The security contact email address for the organization.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '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'
  /organizations/{organization_id}:
    get:
      summary: Get organization
      description: Retrieves the specified organization.
      operationId: get-org
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '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 organization
      description: Updates the specified organization.
      operationId: update-org
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A unique machine name representing the organization.
                label:
                  type: string
                  description: The human-readable label of the organization.
                country:
                  type: string
                  description: The organization country (2-letter country code).
                  maxLength: 2
                security_contact:
                  type: string
                  format: email
                  description: The security contact email address for the organization.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '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 organization
      description: Deletes the specified organization.
      operationId: delete-org
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      responses:
        '204':
          description: No Content
        '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}/metrics/carbon:
    get:
      summary: Query project carbon emissions metrics for an entire organization
      description: Queries the carbon emission data for all projects owned by the specified organiation.
      operationId: query-organiation-carbon
      parameters:
      - $ref: '#/components/parameters/OrganizationID'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/interval'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCarbon'
        '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'
      tags:
      - Organizations
components:
  schemas:
    OrganizationID:
      type: string
      description: The ID of the organization.
    MetricsMetadata:
      type: object
      properties:
        from:
          description: The value used to calculate the lower bound of the temporal query. Inclusive.
        to:
          description: The truncated value used to calculate the upper bound of the temporal query. Exclusive.
        interval:
          description: The interval used to group the metric values.
        units:
          description: The units associated with the provided values.
    CarbonTotal:
      type: number
      description: The calculated total of the metric for the given interval.
    ProjectID:
      type: string
      description: The ID of the project.
    MetricsValue:
      type: object
      properties:
        value:
          description: The measured value of the metric for the given time interval.
        start_time:
          description: The timestamp at which the time interval began.
    Link:
      type: object
      title: Link
      description: A hypermedia link to the {current, next, previous} set of items.
      properties:
        href:
          type: string
          description: URL of the link
    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
    MetricsValues:
      type: array
      items:
        $ref: '#/components/schemas/MetricsValue'
    OrganizationProjectCarbon:
      type: object
      properties:
        project_id:
          $ref: '#/components/schemas/ProjectID'
        project_title:
          $ref: '#/components/schemas/ProjectTitle'
        values:
          $ref: '#/components/schemas/MetricsValues'
        total:
          $ref: '#/components/schemas/CarbonTotal'
    DateTimeFilter:
      type: object
      properties:
        eq:
          type: string
          description: Equal
        ne:
          type: string
          description: Not equal
        between:
          type: string
          description: Between (comma-separated list)
        gt:
          type: string
          description: Greater than
        gte:
          type: string
          description: Greater than or equal
        lt:
          type: string
          description: Less than
        lte:
          type: string
          description: Less than or equal
    ArrayFilter:
      type: object
      properties:
        eq:
          type: string
          description: Equal
        ne:
          type: string
          description: Not equal
        in:
          type: string
          description: In (comma-separated list)
        nin:
          type: string
          description: Not in (comma-separated list)
    ListLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Organization:
      type: object
      properties:
        id:
          type: string
          format: ulid
          description: The ID of the organization.
        type:
          type: string
          description: The type of the organization.
          enum:
          - fixed
          - flexible
        owner_id:
          type: string
          format: uuid
          description: The ID of the owner.
        namespace:
          type: string
          description: The namespace in which the organization name is unique.
        name:
          type: string
          description: A unique machine name representing the organization.
        label:
          type: string
          description: The human-readable label of the organization.
        country:
          type: string
          description: The organization country (2-letter country code).
          maxLength: 2
        capabilities:
          type: array
          description: The organization capabilities.
          items:
            type: string
          uniqueItems: true
        vendor:
          type: string
          description: The vendor.
        billing_account_id:
          type: string
          description: The Billing Account ID.
        billing_legacy:
          type: boolean
          description: Whether the account is billed with the legacy system.
        security_contact:
          type: string
          format: email
          description: The security contact email address for the organization.
        status:
          type: string
          description: The status of the organization.
          enum:
          - active
          - restricted
          - suspended
          - deleted
        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.
        _links:
          type: object
          properties:
            self:
              type: object
              description: Link to the current organization.
              properties:
                href:
                  type: string
                  description: URL of the link.
            update:
              type: object
              description: Link for updating the current organization.
              properties:
                href:
                  type: string
                  description: URL of the link.
                method:
                  type: string
                  description: The HTTP method to use.
            delete:
              type: object
              description: Link for deleting the current organization.
              properties:
                href:
                  type: string
                  description: URL of the link.
                method:
                  type: string
                  description: The HTTP method to use.
            members:
              type: object
              description: Link to the current organization's members.
              properties:
                href:
                  type: string
                  description: URL of the link.
            create-member:
              type: object
              description: Link for creating a new organization member.
              properties:
                href:
                  type: string
                  description: URL of the link.
                method:
                  type: string
                  description: The HTTP method to use.
            address:
              type: object
              description: Link to the current organization's address.
              properties:
                href:
                  type: string
                  description: URL of the link.
            profile:
              type: object
              description: Link to the current organization's profile.
              properties:
                href:
                  type: string
                  description: URL of the link.
            payment-source:
              type: object
              description: Link to the current organization's payment source.
              properties:
                href:
                  type: string
                  description: URL of the link.
            orders:
              type: object
              description: Link to the current organization's orders.
              properties:
                href:
                  type: string
                  description: URL of the link.
            vouchers:
              type: object
              description: Link to the current organization's vouchers.
              properties:
                href:
                  type: string
                  description: URL of the link.
            apply-voucher:
              type: object
              description: Link for applying a voucher for the current organization.
              properties:
                href:
                  type: string
                  description: URL of the link.
                method:
                  type: string
                  description: The HTTP method to use.
            subscriptions:
              type: object
              description: Link to the current organization's subscriptions.
              properties:
                href:
                  type: string
                  description: URL of the link.
            create-subscription:
              type: object
              description: Link for creating a new organization subscription.
              properties:
                href:
                  type: string
                  description: URL of the link.
                method:
                  type: string
                  description: The HTTP method to use.
            estimate-subscription:
              type: object
              description: Link for estimating the price of a new subscription.
              properties:
                href:
                  type: string
                  description: URL of the link.
            mfa-enforcement:
              type: object
              description: Link to the current organization's MFA enforcement settings.
              properties:
                href:
                  type: string
                  description: URL of the link.
    StringFilter:
      type: object
      properties:
        eq:
          type: string
          description: Equal
        ne:
          type: string
          description: Not equal
        in:
          type: string
          description: In (comma-separated list)
        nin:
          type: string
          description: Not in (comma-separated list)
        between:
          type: string
          description: Between (comma-separated list)
        contains:
          type: string
          description: Contains
        starts:
          type: string
          description: Starts with
        ends:
          type: string
          description: Ends with
    OrganizationCarbon:
      type: object
      properties:
        organization_id:
          $ref: '#/components/schemas/OrganizationID'
        meta:
          $ref: '#/components/schemas/MetricsMetadata'
        projects:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationProjectCarbon'
        total:
          $ref: '#/components/schemas/CarbonTotal'
    ProjectTitle:
      type: string
      description: The title of the project.
  parameters:
    to:
      in: query
      name: to
      description: The end of the time frame for the query. Exclusive.
      schema:
        $ref: '#/components/schemas/DateTimeFilter'
    interval:
      in: query
      name: interval
      description: The interval by which the query groups the results. of the time frame for the query. Exclusive.
 

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