Platform.sh References API

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