Broad Institute CromIAM Workflows (for Job Manager) API

openapi: 3.2.0
info:
  title: Terra CromIAM Workflows (for Job Manager) 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: CromIAM Workflows (for Job Manager)
paths:
  /api/workflows/{version}/{id}/abort:
    post:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Abort a workflow based on workflow id
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - name: id
        in: path
        description: Workflow ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStatusResponse'
        400:
          description: Malformed Workflow ID
          content: {}
        403:
          description: Workflow in terminal status
          content: {}
        404:
          description: Workflow ID Not Found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      operationId: postApiWorkflowsByVersionByIdAbort
      x-operation-id-source: derived
  /api/workflows/{version}/{id}/cost:
    get:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Get estimated cloud costs incurred by this workflow so far (not predictive)
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - name: id
        in: path
        description: Workflow ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostResponse'
        400:
          description: Malformed Workflow ID
          content: {}
        404:
          description: Workflow ID Not Found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      operationId: getApiWorkflowsByVersionByIdCost
      x-operation-id-source: derived
  /api/workflows/{version}/{id}/labels:
    patch:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Add new labels or update values for existing label keys by workflow id
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - name: id
        in: path
        description: Workflow ID
        required: true
        schema:
          type: string
      requestBody:
        description: 'Custom labels submitted as JSON. Example: {"key-1":"value-1","key-2":"value-2"}

          '
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
        400:
          description: Malformed Workflow ID
          content: {}
        404:
          description: Workflow ID Not Found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      x-codegen-request-body-name: labels
      operationId: patchApiWorkflowsByVersionByIdLabels
      x-operation-id-source: derived
  /api/workflows/{version}/{id}/metadata:
    get:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Query for workflow and call-level metadata for a specified workflow
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - name: id
        in: path
        description: Workflow ID
        required: true
        schema:
          type: string
      - name: includeKey
        in: query
        description: 'When specified key(s) to include from the metadata. Matches any key starting with the value. May not be used with excludeKey.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: excludeKey
        in: query
        description: 'When specified key(s) to exclude from the metadata. Matches any key starting with the value. May not be used with includeKey.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: expandSubWorkflows
        in: query
        description: 'When true, metadata for sub workflows will be fetched and inserted automatically in the metadata response.

          '
        schema:
          type: boolean
          default: false
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowMetadataResponse'
            workflowName:
              example: example
            calls:
              example:
                example.gather:
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-gather/stdout
                  shardIndex: -1
                  outputs:
                    str: '_one_

                      _two_

                      _three_

                      _four_'
                  inputs:
                    array: analysis.out
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:23-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-gather/stderr
                  executionEvents:
                  - description: execution event - only one in this call, some calls might have none!
                    startTime: 2015-12-11 16:53:23-05:00
                    endTime: 2015-12-11 16:53:23-05:00
                  start: 2015-12-11 16:53:23-05:00
                example.prepare:
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-prepare/stdout
                  shardIndex: -1
                  outputs:
                    array:
                    - one
                    - two
                    - three
                    - four
                  inputs: {}
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:22-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-prepare/stderr
                  executionEvents: []
                  start: 2015-12-11 16:53:21-05:00
                example.analysis:
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-0/stdout
                  shardIndex: 0
                  outputs:
                    out: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-0/a.txt
                  inputs:
                    str: x
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:23-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-0/stderr
                  executionEvents: []
                  start: 2015-12-11 16:53:22-05:00
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-1/stdout
                  shardIndex: 1
                  outputs:
                    out: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-1/a.txt
                  inputs:
                    str: x
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:23-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-1/stderr
                  executionEvents: []
                  start: 2015-12-11 16:53:22-05:00
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-2/stdout
                  shardIndex: 2
                  outputs:
                    out: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-2/a.txt
                  inputs:
                    str: x
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:23-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-2/stderr
                  executionEvents: []
                  start: 2015-12-11 16:53:22-05:00
                - executionStatus: Done
                  stdout: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-3/stdout
                  shardIndex: 3
                  outputs:
                    out: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-3/a.txt
                  inputs:
                    str: x
                  returnCode: 0
                  backend: Local
                  end: 2015-12-11 16:53:23-05:00
                  stderr: /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-3/stderr
                  executionEvents: []
                  start: 2015-12-11 16:53:22-05:00
            outputs:
              example:
                example.analysis.out:
                - /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-0/a.txt
                - /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-1/a.txt
                - /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-2/a.txt
                - /cromwell/cromwell-executions/example/e552029e-4b9a-48e9-b11f-6e5d6d0dccc4/call-analysis/shard-3/a.txt
                example.gather.str: '_one_

                  _two_

                  _three_

                  _four_'
                example.prepare.array:
                - one
                - two
                - three
                - four
            id:
              example: e552029e-4b9a-48e9-b11f-6e5d6d0dccc4
            inputs:
              example:
                test.hello.name: chris
                blah2.grep.pattern: h
                blah2.cat.asdf: gs://cromwell-root/blah/c0c116ef-aac6-4029-8d0a-70d86b17c843/call-ls/job.stdout.txt
                blah.grep.pattern: v
                blah.ls.pattern: ./
            submission:
              example: 2015-12-11 16:53:21-05:00
            status:
              example: Succeeded
            end:
              example: 2015-12-11 16:53:23-05:00
            start:
              example: 2015-12-11 16:53:21-05:00
        400:
          description: Malformed Workflow ID
          content: {}
        404:
          description: Workflow ID Not Found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      operationId: getApiWorkflowsByVersionByIdMetadata
      x-operation-id-source: derived
  /api/workflows/{version}/query:
    get:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Query workflows by start dates, end dates, names, ids, or statuses
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - name: start
        in: query
        description: 'Returns only workflows with an equal or later start datetime.  Can be specified at most once. If both start and end date are specified, start date must be before or equal to end date.

          '
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: 'Returns only workflows with an equal or earlier end datetime.  Can be specified at most once. If both start and end date are specified, start date must be before or equal to end date.

          '
        schema:
          type: string
          format: date-time
      - name: status
        in: query
        description: 'Returns only workflows with the specified status.  If specified multiple times, returns workflows in any of the specified statuses.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          enum:
          - Submitted
          - Running
          - Aborting
          - Failed
          - Succeeded
          - Aborted
      - name: name
        in: query
        description: 'Returns only workflows with the specified name.  If specified multiple times, returns workflows with any of the specified names.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: id
        in: query
        description: 'Returns only workflows with the specified workflow id.  If specified multiple times, returns workflows with any of the specified workflow ids.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowQueryResponse'
        403:
          description: Malformed Request
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      operationId: getApiWorkflowsByVersionQuery
      x-operation-id-source: derived
    post:
      tags:
      - CromIAM Workflows (for Job Manager)
      summary: Query workflows by start dates, end dates, names, ids, or statuses
      parameters:
      - $ref: '#/components/parameters/versionParam'
      requestBody:
        description: 'Same query parameters as GET /query endpoint, submitted as a json list. Example: [{"status":"Success"},{"status":"Failed"}]

          '
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/WorkflowQueryParameter'
        required: true
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowQueryResponse'
        400:
          description: Malformed Request
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: cromiam
      x-codegen-request-body-name: parameters
      operationId: postApiWorkflowsByVersionQuery
      x-operation-id-source: derived
components:
  schemas:
    LabelsResponse:
      required:
      - id
      - labels
      type: object
      properties:
        id:
          type: string
          description: The identifier of the workflow
        labels:
          type: string
          description: The custom labels as json
    CallMetadata:
      type: object
      properties:
        inputs:
          type: object
          additionalProperties:
            type: object
          description: map from input names onto resolved values
        executionStatus:
          type: string
          description: status of call
        executionEvents:
          type: array
          items:
            $ref: '#/components/schemas/ExecutionEvent'
        backendStatus:
          type: string
          description: status of the backend
        backendLogs:
          type: object
          additionalProperties:
            type: string
          description: map of log files from backend
        outputs:
          type: object
          additionalProperties:
            type: string
          description: map from output names to local files
        start:
          type: string
          description: starting time of call
          format: date-time
        end:
          type: string
          description: ending time of call
          format: date-time
        jobId:
          type: string
          description: unique ID of job
        returnCode:
          type: integer
          description: result code
          format: int32
        backend:
          type: string
          description: type of backend executing the call
        stdout:
          type: string
          description: location of stdout
        stderr:
          type: string
          description: location of stderr
        shardIndex:
          type: integer
          description: call index within a scatter block, as reported by execution service
          format: int32
      description: Stuff you need to know about calls
    FailureMessage:
      required:
      - failure
      - timestamp
      type: object
      properties:
        failure:
          type: string
          description: The failure message
        timestamp:
          type: string
          description: The time at which this failure occurred
          format: date-time
      description: Failure messages
    WorkflowQueryResult:
      required:
      - id
      - name
      - start
      - status
      type: object
      properties:
        id:
          type: string
          description: Workflow ID
        name:
          type: string
          description: Workflow name
        status:
          type: string
          description: Workflow status
        start:
          type: string
          description: Workflow start datetime
          format: date-time
        end:
          type: string
          description: Workflow end datetime
          format: date-time
      description: Result for an individual workflow returned by a workflow query
    WorkflowMetadataResponse:
      required:
      - id
      - status
      - submission
      type: object
      properties:
        id:
          type: string
          description: The identifier of the workflow
        status:
          type: string
          description: The status of the workflow
        submission:
          type: string
          description: Submission datetime of the workflow in ISO8601 format with milliseconds
          format: date-time
        start:
          type: string
          description: Start datetime of the workflow in ISO8601 format with milliseconds
          format: date-time
        end:
          type: string
          description: End datetime of the workflow in ISO8601 format with milliseconds
          format: date-time
        inputs:
          type: object
          additionalProperties:
            type: object
          description: Map of input keys to input values
        outputs:
          type: object
          additionalProperties:
            type: object
          description: Map of output keys to output values
        calls:
          $ref: '#/components/schemas/CallMetadata'
        failures:
          $ref: '#/components/schemas/FailureMessage'
      description: Workflow and call level metadata
    WorkflowStatusResponse:
      required:
      - id
      - status
      type: object
      properties:
        id:
          type: string
          description: The identifier of the workflow
        status:
          type: string
          description: The status of the workflow
    WorkflowQueryParameter:
      type: object
      properties:
        start:
          type: string
          description: 'Returns only workflows with an equal or later start datetime.  Can be specified at most once. If both start and end date are specified, start date must be before or equal to end date.

            '
          format: date-time
        end:
          type: string
          description: 'Returns only workflows with an equal or earlier end datetime.  Can be specified at most once. If both start and end date are specified, start date must be before or equal to end date.

            '
          format: date-time
        status:
          type: string
          description: 'Returns only workflows with the specified status.  If specified multiple times, returns workflows in any of the specified statuses.

            '
          enum:
          - Submitted
          - Running
          - Aborting
          - Failed
          - Succeeded
          - Aborted
        name:
          pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
          type: string
          description: 'Returns only workflows with the specified name.  If specified multiple times, returns workflows with any of the specified names.

            '
        id:
          pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
          type: string
          description: 'Returns only workflows with the specified workflow id.  If specified multiple times, returns workflows with any of the specified workflow ids.

            '
      description: Workflow query parameters
    ExecutionEvent:
      required:
      - description
      - startTime
      type: object
      properties:
        description:
          type: string
          description: Description of the event
        startTime:
          type: string
          description: When the event started
          format: date-time
        endTime:
          type: string
          description: When the event finished
          format: date-time
      description: ''
    WorkflowQueryResponse:
      required:
      - results
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowQueryResult'
      description: Response to a workflow query
    CostResponse:
      required:
      - cost
      - currency
      - errors
      - id
      - status
      type: object
      properties:
        cost:
          type: number
          description: The current estimated cost of the workflow
          example: 0.045
        currency:
          type: string
          description: The currency that the cost is in, currently always USD
          example: USD
        errors:
          type: array
          items:
            type: string
          description: Errors that were encountered while obtaining cost information, if any. If this list is nonempty the estimated cost should be regarded as incomplete.
        id:
          type: string
          description: The identifier of the workflow
          example: 00001111-2222-3333-aaaa-bbbbccccdddd
        status:
          type: string
          description: The status of the workflow
          example: Running
  parameters:
    versionParam:
      name: version
      in: path
      description: Cromwell API Version
      required: true
      schema:
        type: string
        default: v1
  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