Broad Institute Submissions API

openapi: 3.2.0
info:
  title: Terra Submissions 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: Submissions
paths:
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions:
    get:
      tags:
      - Submissions
      summary: List submissions
      operationId: listSubmissions
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      responses:
        200:
          description: List of submissions
          content: {}
        404:
          description: Workspace not found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
    post:
      tags:
      - Submissions
      summary: Create a submission
      operationId: createSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Post Submission
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionRequest'
        required: true
      responses:
        201:
          description: Successful Request
          content: {}
        400:
          description: Expression eval failed or entities are not of type required by method config
          content: {}
        404:
          description: Method Configuration or Entity not found
          content: {}
        409:
          description: Method Configuration failed to resolve input expressions with the supplied Entity
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
      x-codegen-request-body-name: submission
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissionsCount:
    get:
      tags:
      - Submissions
      summary: Count submissions by status
      description: Counts all submissions run in the workspace, grouped by status. Returns a map of status:count.
      operationId: countSubmissions
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionsCountResponse'
        404:
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions/{submissionId}:
    get:
      tags:
      - Submissions
      summary: Monitor submission status
      operationId: monitorSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        404:
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
    delete:
      tags:
      - Submissions
      summary: abort a submission
      operationId: abortSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      responses:
        204:
          description: Aborted successfully
          content: {}
        404:
          description: Submission not found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
    patch:
      tags:
      - Submissions
      summary: Update user comment for a submission
      operationId: updateSubmissionUserComment
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      requestBody:
        description: User comment to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCommentUpdateOperation'
        required: true
      responses:
        200:
          description: Successful Request
        404:
          description: Workspace or submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Rawls Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions/validate:
    post:
      tags:
      - Submissions
      summary: Validate submission
      description: Validate expression syntax for a submission
      operationId: validateSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Description of a submission.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionRequest'
        required: true
      responses:
        200:
          description: Validation Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionValidationReport'
        400:
          description: Expression evaluation failed or entities are not of type required by method config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        404:
          description: Workspace, Method Configuration or Entity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Rawls Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        502:
          description: Trouble talking to Agora
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
      x-codegen-request-body-name: submission
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions/{submissionId}/workflows/{workflowId}:
    get:
      tags:
      - Submissions
      summary: Get call-level metadata for workflow
      operationId: workflowMetadata
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      - $ref: '#/components/parameters/workflowIdParam'
      - name: includeKey
        in: query
        description: 'When specified, return only these keys in the response. Matches any key in the response, including within nested blocks. May not be used with excludeKey.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: excludeKey
        in: query
        description: 'When specified, omit these keys from the response. Matches any key in the response, including within nested blocks. 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: {}
        404:
          description: Workspace, Submission or Workflow not 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
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions/{submissionId}/workflows/{workflowId}/outputs:
    get:
      tags:
      - Submissions
      summary: Get workflow outputs
      operationId: workflowOutputsInSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      - $ref: '#/components/parameters/workflowIdParam'
      responses:
        200:
          description: Get workflow outputs
          content: {}
        404:
          description: Workspace, Submission or Workflow not found
          content: {}
        500:
          description: Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
  /api/workspaces/{workspaceNamespace}/{workspaceName}/submissions/{submissionId}/workflows/{workflowId}/cost:
    get:
      tags:
      - Submissions
      summary: Retrieve workflow cost, if available
      operationId: workflowCostInSubmission
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - $ref: '#/components/parameters/submissionIdParam'
      - $ref: '#/components/parameters/workflowIdParam'
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowCost'
        404:
          description: Workspace, Submission or Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: rawls
components:
  schemas:
    SubmissionValidationInput:
      required:
      - expression
      - wdlName
      type: object
      properties:
        wdlName:
          type: string
          description: name of input
        expression:
          type: string
          description: expression for input
      description: method configuration input parameter, it's name and the associated expression from the method config
    SubmissionValidationEntityInputs:
      required:
      - entityName
      - inputResolutions
      type: object
      properties:
        entityName:
          type: string
          description: name of entity
        inputResolutions:
          type: array
          description: input resolution
          items:
            $ref: '#/components/schemas/SubmissionValidationValue'
      description: the results of parsing each of the inputs for one entity
    UserCommentUpdateOperation:
      required:
      - userComment
      type: object
      properties:
        userComment:
          type: string
          description: The updated value for user comment (max length 1000 characters)
      description: Update user comment for submission
    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: ''
    SubmissionRequest:
      required:
      - methodConfigurationName
      - methodConfigurationNamespace
      - useCallCache
      type: object
      properties:
        methodConfigurationNamespace:
          type: string
          description: Namespace of the method configuration to execute.
        methodConfigurationName:
          type: string
          description: Name of the method configuration to execute.
        entityType:
          type: string
          description: Type of root entity for expression. Optional if the method configuration has no root entity.
        entityName:
          type: string
          description: Name of root entity for expression. Optional if the method configuration has no root entity.
        expression:
          type: string
          description: Expression that resolves to one or more entities matching the entity type in the method configuration. Optional if the method configuration has no root entity.
        useCallCache:
          type: boolean
          description: Whether or not to read from cache for this submission.
        deleteIntermediateOutputFiles:
          type: boolean
          description: Whether or not to delete intermediate output files when the workflow completes. See Cromwell docs for more information.
        useReferenceDisks:
          type: boolean
          description: Whether or not to use pre-built disks for common genome references
        memoryRetryMultiplier:
          type: number
          description: If a task fails due to running out of memory and the task has `maxRetries` in its runtime attributes, then it will be retried with its memory multiplied by this amount.  See [Cromwell docs](https://cromwell.readthedocs.io/en/develop/cromwell_features/RetryWithMoreMemory/#retry-with-more-memory) for more information.
        workflowFailureMode:
          type: string
          description: What happens after a task fails. Choose from ContinueWhilePossible and NoNewCalls. Defaults to NoNewCalls if not specified. See Cromwell docs for more information.
          default: NoNewCalls
          enum:
          - NoNewCalls
          - ContinueWhilePossible
        userComment:
          type: string
          description: Freeform user defined description, optional (max length 1000 characters)
        ignoreEmptyOutputs:
          type: boolean
          default: false
          description: Whether or not to create output columns if they would be empty and optional.  Defaults to false (columns are created).
        perWorkflowCostCap:
          type: number
          description: A cost threshold in USD to apply to individual workflows. When the estimated cost is exceeded, the workflow is terminated.
          format: float
          minimum: 0.01
          maximum: 9999999999.99
          multipleOf: 0.01
      description: If the referenced method configuration takes no root entity, do not define `entityType`, `entityName` and `expression`.
    Submission:
      type: object
      properties:
        submissionId:
          type: string
          description: SubmissionRequest unique identifier
        submissionDate:
          type: string
          description: SubmissionRequest date
          format: date-time
        submitter:
          type: string
          description: user that created the submission
        methodConfigurationNamespace:
          type: string
          description: Method configuration namespace
        methodConfigurationName:
          type: string
          description: Method configuration name
        submissionEntity:
          $ref: '#/components/schemas/AttributeEntityReference'
        workflows:
          type: array
          description: Status of Workflow(s)
          items:
            $ref: '#/components/schemas/Workflow'
        status:
          $ref: '#/components/schemas/SubmissionStatus'
        cost:
          type: number
          description: The compute cost of this submission
          format: float
        useCallCache:
          type: boolean
          description: Whether or not to read from cache for this submission
        deleteIntermediateOutputFiles:
          type: boolean
          description: Whether or not to delete intermediate output files when the workflow completes. See Cromwell docs for more information.
        useReferenceDisks:
          type: boolean
          description: Whether or not to use pre-built disks for common genome references
        memoryRetryMultiplier:
          type: number
          description: If a task fails due to running out of memory and the task has `maxRetries` in its runtime attributes, then it will be retried with its memory multiplied by this amount.  See [Cromwell docs](https://cromwell.readthedocs.io/en/develop/cromwell_features/RetryWithMoreMemory/#retry-with-more-memory) for more information.
        workflowFailureMode:
          type: string
          description: What happens after a task fails. Choose from ContinueWhilePossible and NoNewCalls. Defaults to NoNewCalls if not specified. See Cromwell docs for more information.
          default: NoNewCalls
          enum:
          - NoNewCalls
          - ContinueWhilePossible
        userComment:
          type: string
          description: Comment for the submission
      description: ''
    Workflow:
      type: object
      properties:
        workflowId:
          type: string
          description: Workflow unique identifier
        status:
          $ref: '#/components/schemas/WorkflowStatus'
        statusLastChangedDate:
          type: string
          description: Status last-changed date
          format: date-time
        workflowEntity:
          $ref: '#/components/schemas/AttributeEntityReference'
        inputResolutions:
          type: array
          description: The evaluation of each input
          items:
            $ref: '#/components/schemas/SubmissionValidationValue'
        messages:
          type: array
          description: List of messages about this workflow
          items:
            type: string
        cost:
          type: number
          description: The run cost of this workflow, if available
          format: float
        costType:
          type: string
          description: The method used to calculate the run cost
          enum:
          - Actual
          - Estimated
      description: ''
    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: ''
    AttributeEntityReference:
      required:
      - entityName
      - entityType
      type: object
      properties:
        entityType:
          type: string
          description: The type of the entity
        entityName:
          type: string
          description: The name of the entity
      description: ''
    SubmissionStatus:
      type: string
      description: submission status
      enum:
      - Accepted
      - Evaluating
      - Submitting
      - Submitted
      - Aborting
      - Aborted
      - Done
    SubmissionValidationReport:
      required:
      - header
      - invalidEntities
      - request
      - validEntities
      type: object
      properties:
        header:
          $ref: '#/components/schemas/SubmissionValidationHeader'
        validEntities:
          type: array
          description: runnable entities
          items:
            $ref: '#/components/schemas/SubmissionValidationEntityInputs'
        invalidEntities:
          type: array
          description: non-runnable entities
          items:
            $ref: '#/components/schemas/SubmissionValidationEntityInputs'
        request:
          $ref: '#/components/schemas/SubmissionRequest'
      description: the results of parsing each input for each entity
    WorkflowCost:
      type: object
      properties:
        cost:
          type: number
          description: Workflow cost
          format: float
        workflowId:
          type: string
          description: The id of this workflow
      description: The cost of a workflow, if available
    WorkflowStatus:
      type: string
      description: workflow status
      enum:
      - Queued
      - Launching
      - Submitted
      - Running
      - Failed
      - Succeeded
      - Aborting
      - Aborted
      - Unknown
    SubmissionValidationHeader:
      required:
      - entityType
      - inputExpressions
      type: object
      properties:
        entityType:
          type: string
          description: type of entity
        inputExpressions:
          type: array
          description: input descriptions
          items:
            $ref: '#/components/schemas/SubmissionValidationInput'
      description: common values for all the entities -- the entity type and the input descriptions
    SubmissionsCountResponse:
      type: object
      properties:
        Accepted:
          type: integer
          format: int32
        Evaluating:
          type: integer
          format: int32
        Submitting:
          type: integer
          format: int32
        Submitted:
          type: integer
          format: int32
        Aborting:
          type: integer
          format: int32
        Aborted:
          type: integer
          format: int32
        Done:
          type: integer
          format: int32
    SubmissionValidationValue:
      required:
      - inputName
      type: object
      properties:
        value:
          type: string
          description: the value of the input expression for the specified entity
        error:
          type: string
          description: parsing error(s)
        inputName:
          type: string
          description: name of input
      description: result of an expression parse for one of the inputs
  parameters:
    workspaceNameParam:
      name: workspaceName
      in: path
      description: Workspace Name
      required: true
      schema:
        type: string
    submissionIdParam:
      name: submissionId
      in: path
      description: Submission ID
      required: true
      schema:
        type: string
    workspaceNamespaceParam:
      name: workspaceNamespace
      in: path
      description: Workspace Namespace
      required: true
      schema:
        type: string
    workflowIdParam:
      name: workflowId
      in: path
      description: Workflow ID
      required: true
      schema:
        type: string
  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