Broad Institute Billing V2 API

openapi: 3.2.0
info:
  title: Terra Billing V2 API
  description: Terra API
  termsOfService: https://app.terra.bio/#terms-of-service
  license:
    name: BSD
    url: http://opensource.org/licenses/BSD-3-Clause
  version: '0.1'
servers:
- url: /
security:
- oidc: []
tags:
- name: BillingV2
paths:
  /api/billing/v2/{projectId}/spendReportConfiguration:
    get:
      tags:
      - BillingV2
      summary: get the spend report configuration for the billing project
      operationId: getSpendReportConfiguration
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        200:
          description: Successfully retrieved spend report configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendReportConfiguration'
        204:
          description: The specified billing project exists but does not have spend reporting configured
        403:
          description: You must be a billing project owner to view the spend report configuration of the billing project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: The specified billing project could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Rawls Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
    put:
      tags:
      - BillingV2
      summary: set the spend configuration for the billing project
      operationId: setSpendReportConfiguration
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      requestBody:
        description: billing project spend configuration information
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendReportConfiguration'
      responses:
        204:
          description: Successfully updated spend configuration
        400:
          description: Either the billing project does not have an active billing account, the specified dataset does not exist, or the specified table does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        403:
          description: You must be a billing project owner to alter the spend configuration of the billing project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: The specified billing project could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Rawls Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
    delete:
      tags:
      - BillingV2
      summary: clear the spend configuration for the billing project
      operationId: clearSpendReportConfiguration
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        204:
          description: Successfully cleared spend configuration
        403:
          description: You must be a billing project owner to alter the spend configuration of the billing project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Rawls Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
  /api/billing/v2:
    get:
      tags:
      - BillingV2
      summary: list billing projects for a user
      operationId: listUserBillingProjectsV2
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                type: array
                description: list of billing projects for this user
                items:
                  $ref: '#/components/schemas/RawlsBillingProjectResponse'
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          $ref: '#/components/responses/RawlsInternalError'
    post:
      tags:
      - BillingV2
      summary: create billing project in rawls
      description: create new billing project in rawls; the client must provide either Azure managed app coordinates or a Google billing account ID. Providing both will result in an error.
      operationId: createBillingProjectFullV2
      requestBody:
        description: create project request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRawlsV2BillingProjectFullRequest'
        required: true
      responses:
        201:
          description: Successfully Created Billing Project in Terra
        400:
          description: both you and Terra billing user must be a user of the billing account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        409:
          description: project already exists in rawls
          content: {}
        500:
          description: FireCloud Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      security:
      - oidc_google_billing_scope: []
      x-codegen-request-body-name: createProjectRequest
  /api/billing/v2/{projectId}:
    get:
      tags:
      - BillingV2
      summary: get billing project
      operationId: getBillingProject
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RawlsBillingProjectResponse'
        404:
          description: Project Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
    delete:
      tags:
      - BillingV2
      summary: delete billing project
      operationId: deleteBillingProject
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        204:
          description: OK
        404:
          description: Project Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
  /api/billing/v2/{projectId}/billingAccount:
    put:
      tags:
      - BillingV2
      summary: update billing account on billing project
      description: Update the Billing Account on the Billing Project and on each Workspace in the Billing Project
      operationId: updateBillingProjectBillingAccount
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      requestBody:
        description: update billing account request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRawlsBillingAccountRequest'
        required: true
      responses:
        200:
          description: Billing Account on Billing Project is successfully updated and process is started to update the Billing Account on each Workspace in the Billing Project
        400:
          description: Billing account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: Billing Project Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      security:
      - oidc_google_billing_scope: []
      x-passthrough: true
      x-passthrough-target: rawls
    delete:
      tags:
      - BillingV2
      summary: deletes the billing account on billing project
      description: Clears the Billing Account on the Billing Project and on each Workspace in the Billing Project
      operationId: deleteBillingProjectBillingAccount
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        200:
          description: Billing account successfully removed
        404:
          description: Billing project Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
  /api/billing/v2/{projectId}/members:
    get:
      tags:
      - BillingV2
      summary: list members of billing project the caller owns
      operationId: listBillingProjectMembersV2
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingProjectMember'
        403:
          description: You must be a project owner to view the members of a project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: FireCloud Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
  /api/billing/v2/{projectId}/members/{workbenchRole}/{email}:
    put:
      tags:
      - BillingV2
      summary: add user or group to billing project the caller owns
      operationId: addUserToBillingProjectV2
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      - name: workbenchRole
        in: path
        description: role of user for project
        required: true
        schema:
          type: string
          enum:
          - user
          - owner
      - name: email
        in: path
        description: email of user or group to add
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successfully Added User/Group To Billing Project
        403:
          description: You must be a project owner to add a user to a billing project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: FireCloud Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
    delete:
      tags:
      - BillingV2
      summary: remove user or group from billing project the caller owns
      operationId: removeUserFromBillingProjectV2
      parameters:
      - $ref: '#/components/parameters/billingProjectPathParam'
      - name: workbenchRole
        in: path
        description: role of user for project
        required: true
        schema:
          type: string
          enum:
          - user
          - owner
      - name: email
        in: path
        description: email of user or group to remove
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successfully Removed User From Billing Project
        403:
          description: You must be a project owner to add a user to a billing project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: FireCloud Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
components:
  schemas:
    UpdateRawlsBillingAccountRequest:
      required:
      - billingAccount
      type: object
      properties:
        billingAccount:
          type: string
          description: The name of the billing account to use
    ErrorReport:
      required:
      - causes
      - message
      - source
      - stackTrace
      type: object
      properties:
        source:
          type: string
          description: service causing error
        message:
          type: string
          description: what went wrong
        statusCode:
          type: integer
          description: HTTP status code
          format: int32
        causes:
          type: array
          description: errors triggering this one
          items:
            $ref: '#/components/schemas/ErrorReport'
        stackTrace:
          type: array
          description: stack trace
          items:
            $ref: '#/components/schemas/StackTraceElement'
      description: ''
    ProjectRole:
      description: the role on the billing project
      type: string
      enum:
      - owner
      - user
    AzureManagedAppCoordinates:
      required:
      - tenantId
      - subscriptionId
      - managedResourceGroupId
      type: object
      properties:
        tenantId:
          type: string
          format: uuid
          description: UUID of the Azure tenant for this managed application deployment
        subscriptionId:
          type: string
          format: uuid
          description: UUID of the Azure subscription for this managed application deployment.
        managedResourceGroupId:
          type: string
          description: ID of the Azure managed resource group for this managed application deployment.
    RawlsBillingProjectResponse:
      required:
      - id
      - projectName
      - invalidBillingAccount
      - roles
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the uuid of the project
        projectName:
          type: string
          description: the name of the project
        billingAccount:
          type: string
          description: the billing account to use in google projects
        servicePerimeter:
          type: string
          description: the name of the service parameters for google project
        invalidBillingAccount:
          type: boolean
          description: whether or not the billing account is usable by Terra
        roles:
          type: array
          items:
            type: string
          description: the roles the caller has on the project
        status:
          type: string
          enum:
          - Creating
          - Ready
          - Error
          - Deleting
          - DeletionFailed
          - AddingToPerimeter
          - CreatingLandingZone
          description: the status of allocating the billing project's resources.
        message:
          type: string
          description: informational message about the project
        azureManagedAppCoordinates:
          $ref: '#/components/schemas/AzureManagedAppCoordinates'
        cloudPlatform:
          type: string
          enum:
          - GCP
          - AZURE
          - UNKNOWN
        landingZoneId:
          type: string
          format: uuid
          description: the UUID of the landing zone associated with the project (cloudPlatform AZURE only)
        organization:
          $ref: '#/components/schemas/RawlsBillingProjectOrganization'
    SpendReportConfiguration:
      required:
      - datasetGoogleProject
      - datasetName
      type: object
      properties:
        datasetGoogleProject:
          type: string
          description: the name of the Google Project where the BigQuery dataset resides
        datasetName:
          type: string
          description: the name of the BigQuery dataset containing project spend data
      description: ''
    ProjectAccessUpdate:
      required:
      - email
      - role
      type: object
      properties:
        email:
          description: the email of the member to modify access for
          type: string
        role:
          description: the role to modify for the specified member
          $ref: '#/components/schemas/ProjectRole'
    BillingProjectMember:
      required:
      - email
      - role
      type: object
      properties:
        email:
          type: string
          description: the email of the user
        role:
          type: string
          description: the role of the user in the project
      description: ''
    RawlsBillingProjectOrganization:
      required:
      - enterprise
      type: object
      description: Details about billing project's organization. Only present if billing project is backed by a billing profile.
      properties:
        enterprise:
          type: boolean
          description: whether this billing project is part of an enterprise organization i.e. they have a signed business associate agreement (BAA)
    StackTraceElement:
      required:
      - className
      - fileName
      - lineNumber
      - methodName
      type: object
      properties:
        className:
          type: string
          description: class name
        methodName:
          type: string
          description: method name
        fileName:
          type: string
          description: source file name
        lineNumber:
          type: integer
          description: line number
          format: int32
      description: ''
    CreateRawlsV2BillingProjectFullRequest:
      required:
      - projectName
      type: object
      properties:
        projectName:
          type: string
          description: the name of the project to create
        billingAccount:
          type: string
          description: the id of the Google billing account to use, must start with 'billingAccounts/'
        servicePerimeter:
          type: string
          description: The fully qualified name of the GCP service perimeter to put this project into in the form accessPolicies/[POLICY NUMBER]/servicePerimeters/[NAME]. Caller must have the add_project action for this service perimeter in Sam.
        managedAppCoordinates:
          $ref: '#/components/schemas/AzureManagedAppCoordinates'
        members:
          description: The list of members to add to the billing project
          type: array
          items:
            $ref: '#/components/schemas/ProjectAccessUpdate'
        inviteUsersNotFound:
          description: If true, invite the users to Terra if they are not registered in the system. They will be given access to the project when they register.
          type: boolean
        protectedData:
          type: boolean
          description: Optional, false if not specified. Applicable only for azure billing projects. When set, a billing project with suitable infrastructure for protected data workspaces will be created.
        costSavings:
          type: boolean
          description: Optional, false if not specified. Applicable only for azure billing projects. When set, this enables Vertical Pod Autoscaling and Spot Nodes in Azure Kubernetes.
      description: ''
  parameters:
    billingProjectPathParam:
      name: projectId
      in: path
      description: Billing Project ID
      required: true
      schema:
        type: string
  responses:
    RawlsInternalError:
      description: Rawls Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorReport'
  securitySchemes:
    oidc:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL
    oidc_google_billing_scope:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL_WITH_GOOGLE_BILLING_SCOPE
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL_WITH_GOOGLE_BILLING_SCOPE