Cromwell Server REST API

Overview
Describes the REST API provided by a Cromwell server

Version information
Version : 30

License information
License : BSD
License URL : https://github.com/broadinstitute/cromwell/blob/develop/LICENSE.txt
Terms of service : null

Produces

  • application/json

Submit a workflow for execution

POST /api/workflows/{version}

Description

Submits a workflow to Cromwell. Note that this endpoint can accept an unlimited number of input files via workflowInputs_N but swagger needs them to be explicitly defined so we have provided 5 as an example.

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
FormData labels
optional
JSON object of labels to apply to this workflow. file
FormData workflowDependencies
optional
ZIP file containing workflow source files that are used to resolve local imports. This zip bundle will be unpacked in a sandbox accessible to this workflow. file
FormData workflowInputs
optional
JSON or YAML file containing the inputs as an object. For WDL workflows a skeleton file can be generated from WOMtool using the "inputs" subcommand. When multiple files are specified, in case of key conflicts between multiple input JSON files, higher values of x in workflowInputs_x override lower values. For example, an input specified in workflowInputs_3 will override an input with the same name in workflowInputs or workflowInputs_2. Similarly, an input key specified in workflowInputs_5 will override an identical input key in any other input file. file
FormData workflowInputs_2
optional
A second JSON or YAML file containing inputs. file
FormData workflowInputs_3
optional
A third JSON or YAML file containing inputs. file
FormData workflowInputs_4
optional
A fourth JSON or YAML file containing inputs. file
FormData workflowInputs_5
optional
A fifth JSON or YAML file containing inputs. file
FormData workflowOnHold
optional
Put workflow on hold upon submission. By default, it is taken as false. boolean
FormData workflowOptions
optional
JSON file containing configuration options for the execution of this workflow. file
FormData workflowRoot
optional
The root object to be run. Only necessary for CWL submissions containing multiple objects (in an array). string
FormData workflowSource
required
The workflow source file to submit for execution. file
FormData workflowType
optional
The workflow language for the file you submitted. Cromwell currently supports WDL and CWL. enum (WDL, CWL)
FormData workflowTypeVersion
optional
The specification version for the workflow language being used. For WDL, Cromwell currently supports draft-2 and 1.0. For CWL, Cromwell currently supports v1.0. enum (draft-2, 1.0, v1.0)

Responses

HTTP Code Description Schema
201 Successful Request WorkflowIdAndStatus
400 Invalid submission request No Content
500 Internal Error No Content

Consumes

  • multipart/form-data

Tags

  • Workflows

List the supported backends

GET /api/workflows/{version}/backends

Description

Returns the backends supported by this Cromwell server, as well as the default backend.

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request BackendResponse

Tags

  • Workflows

Submit a batch of workflows for execution

POST /api/workflows/{version}/batch

Description

In instances where you want to run the same workflow multiple times with varying inputs you may submit a workflow batch. This endpoint is fundamentally the same as the standard submission endpoint with the exception that the inputs JSON will be an array of objects instead of a single object.

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
FormData labels
optional
JSON object of labels to apply to this workflow. file
FormData workflowDependencies
optional
ZIP file containing workflow source files that are used to resolve local imports. This zip bundle will be unpacked in a sandbox accessible to these workflows. file
FormData workflowInputs
required
JSON file containing the inputs as an array of objects. Every element of the array will correspond to a single workflow. For WDL workflows a skeleton file can be generated from WOMtool using the "inputs" subcommand. When multiple files are specified, in case of key conflicts between multiple input JSON files, higher values of x in workflowInputs_x override lower values. For example, an input specified in workflowInputs_3 will override an input with the same name in workflowInputs or workflowInputs_2. Similarly, an input key specified in workflowInputs_5 will override an identical input key in any other input file. file
FormData workflowOnHold
optional
Put workflow on hold upon submission. By default, it is taken as false. boolean
FormData workflowOptions
optional
JSON file containing configuration options for the execution of this workflow. file
FormData workflowSource
required
The workflow source file to submit for execution. file
FormData workflowType
optional
The workflow language for the file you submitted. Cromwell currently supports WDL and CWL. enum (WDL, CWL)
FormData workflowTypeVersion
optional
The specification version for the workflow language being used. For WDL, Cromwell currently supports draft-2 and 1.0. For CWL, Cromwell currently supports v1.0. enum (draft-2, 1.0, v1.0)

Responses

HTTP Code Description Schema
200 Successful Request < WorkflowIdAndStatus > array
400 Malformed Workflow ID No Content
500 Internal Error No Content

Consumes

  • multipart/form-data

Tags

  • Workflows

Explain hashing differences for 2 calls

GET /api/workflows/{version}/callcaching/diff

Description

This endpoint returns the hash differences between 2 completed (successfully or not) calls.

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
Query callA
required
Fully qualified name, including workflow name, of the first call. string
Query callB
required
Fully qualified name, including workflow name, of the second call string
Query indexA
optional
Shard index for the first call for cases where the requested call was part of a scatter. integer
Query indexB
optional
Shard index for the second call for cases where the requested call was part of a scatter. integer
Query workflowA
required
Workflow Id of the first workflow string
Query workflowB
required
Workflow Id of the second workflow string

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
404 No matching cache entry. Cromwell versions prior to 28 will not have recorded information necessary for this endpoint and thus will also appear to not exist. No Content
500 Internal Error No Content

Tags

  • Workflows

Get workflows matching some criteria

POST /api/workflows/{version}/query

Description

Query workflows by start dates, end dates, names, ids, labels, or statuses.

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
Body parameters
required
Same query parameters as GET /query endpoint, submitted as a json list. Example: [{"status":"Success"},{"status":"Failed"}] < WorkflowQueryParameter > array

Responses

HTTP Code Description Schema
200 Successful Request WorkflowQueryResponse
400 Malformed Workflow ID No Content
500 Internal Error No Content

Tags

  • Workflows

Get workflows matching some criteria

GET /api/workflows/{version}/query

Description

Query for workflows which match various criteria. When a combination of criteria are applied the endpoint will return

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
Query additionalQueryResultFields
optional
Includes the specified keys in the metadata for the returned workflows. < string > array(multi)
Query end
optional
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. string (date-time)
Query excludeLabelAnd
optional
Excludes workflows with the specified label. If specified multiple times, excludes workflows with all of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value" < string > array(multi)
Query excludeLabelOr
optional
Excludes workflows with the specified label. If specified multiple times, excludes workflows with any of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value" < string > array(multi)
Query id
optional
Returns only workflows with the specified workflow id. If specified multiple times, returns workflows with any of the specified workflow ids. < string > array(multi)
Query includeSubworkflows
optional
Include subworkflows in results. By default, it is taken as true. boolean (boolean)
Query label
optional
Returns workflows with the specified label keys. If specified multiple times, returns workflows with all of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value" < string > array(multi)
Query labelor
optional
Returns workflows with the specified label keys. If specified multiple times, returns workflows with any of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value" < string > array(multi)
Query name
optional
Returns only workflows with the specified name. If specified multiple times, returns workflows with any of the specified names. < string > array(multi)
Query start
optional
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. string (date-time)
Query status
optional
Returns only workflows with the specified status. If specified multiple times, returns workflows in any of the specified statuses. < string > array(multi)
Query submission
optional
Returns only workflows with an equal or later submission time. Can be specified at most once. If both submission time and start date are specified, submission time should be before or equal to start date. string (date-time)

Responses

HTTP Code Description Schema
200 Successful Request WorkflowQueryResponse
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Abort a running workflow

POST /api/workflows/{version}/{id}/abort

Description

Request Cromwell to abort a running workflow. For instance this might be necessary in cases where you have submitted a workflow with incorrect inputs or no longer need the results. Cromwell will make a best effort attempt to immediately halt any currently running jobs from this workflow.

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Retrieves the current labels for a workflow

GET /api/workflows/{version}/{id}/labels

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request LabelsResponse
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Update labels for a workflow

PATCH /api/workflows/{version}/{id}/labels

Description

Update multiple labels for an existing workflow. When supplying a label with a key unique to the workflow submission, a new label key/value entry is appended to that workflow's metadata. When supplying a label with a key that is already associated to the workflow submission, the original label value is updated with the new value for that workflow's metadata.

Parameters

Type Name Description Schema Default
Path id
required
Workflow ID string
Path version
required
Cromwell API Version string "v1"
Body labels
required
Custom labels submitted as JSON. Example: {"key-1":"value-1","key-2":"value-2"} object

Responses

HTTP Code Description Schema
200 Successful Request LabelsResponse
400 Malformed Workflow ID No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Get the logs for a workflow

GET /api/workflows/{version}/{id}/logs

Description

Returns paths to the standard out and standard error files that were generated during the execution of all calls in a workflow. A call has one or more standard out and standard error logs, depending on if the call was scattered or not. In the latter case, one log is provided for each instance of the call that has been run.

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Get workflow and call-level metadata for a specified workflow

GET /api/workflows/{version}/{id}/metadata

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"
Query excludeKey
optional
When specified key(s) to exclude from the metadata. Matches any key starting with the value. May not be used with includeKey. This applies to all keys in the response, including within nested blocks. < string > array(multi)
Query expandSubWorkflows
optional
When true, metadata for sub workflows will be fetched and inserted automatically in the metadata response. boolean "false"
Query includeKey
optional
When specified key(s) to include from the metadata. Matches any key starting with the value. May not be used with excludeKey. This applies to all keys in the response, including within nested blocks. < string > array(multi)

Responses

HTTP Code Description Schema
200 Successful Request WorkflowMetadataResponse
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Get the outputs for a workflow

GET /api/workflows/{version}/{id}/outputs

Description

Retrieve the outputs for the specified workflow. Cromwell will return any outputs which currently exist even if a workflow has not successfully completed.

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Switch a workflow from 'On Hold' to 'Submitted' status

POST /api/workflows/{version}/{id}/releaseHold

Description

Request Cromwell to release the hold on a workflow. It will switch the status of a workflow from 'On Hold' to 'Submitted' so it can be picked for running. For instance this might be necessary in cases where you have submitted a workflow with workflowOnHold = true.

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Retrieves the current state for a workflow

GET /api/workflows/{version}/{id}/status

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Get a visual diagram of a running workflow

GET /api/workflows/{version}/{id}/timing

Description

Returns a javascript file which will render a Gantt chart for the requested workflow. The bars in the chart represent start and end times for individual task invocations. This javascript is intended to be embedded into another web page.

Parameters

Type Name Description Schema Default
Path id
required
A workflow ID string
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request WorkflowIdAndStatus
400 Malformed Workflow ID No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • Workflows

Returns basic statistics from this Cromwell server.

GET /engine/{version}/stats

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request StatsResponse

Tags

  • Engine

Return the current health status of any monitored subsystems

GET /engine/{version}/status

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 All subsystems report an "ok" status StatusResponse
500 At least one subsystem does not have an "ok" status StatusResponse

Tags

  • Engine

Return the version of this Cromwell server

GET /engine/{version}/version

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"

Responses

HTTP Code Description Schema
200 Successful Request VersionResponse

Tags

  • Engine

Definitions

BackendResponse

Name Description Schema
defaultBackend
required
The default backend of this server string
supportedBackends
required
The backends supported by this server < string > array

CallMetadata

Call level metadata

Name Description Schema
backend
optional
The type of backend on which the call executed (e.g. JES, SGE, Local) string
backendLogs
optional
Paths to backend specific logs for this call object
backendStatus
optional
Status in backend-specific terms. Currently this will only be defined for the JES backend. string
end
optional
End datetime of the call execution in ISO8601 format with milliseconds string (date-time)
executionStatus
required
Status in Cromwell execution terms. string
failures
optional
FailureMessage
inputs
required
Mapping of input fully qualified names to stringified values object
jobId
optional
Backend-specific job ID string
returnCode
optional
Call execution return code integer
start
optional
Start datetime of the call execution in ISO8601 format with milliseconds string (date-time)
stderr
optional
Path to the standard error file for this call string
stdout
optional
Path to the standard output file for this call string

FailureMessage

Failure messages

Name Description Schema
failure
required
The failure message string
timestamp
required
The time at which this failure occurred string (date-time)

LabelsResponse

Name Description Schema
id
required
The identifier of the workflow
Example : "label-key-1"
string
labels
required
The labels which have been updated
Example : "label-value-1"
string

StatsResponse

Provides engine level statistics for things running inside the system

Name Description Schema
jobs
required
The number of currently running jobs integer
workflows
required
The number of currently running workflows integer

StatusResponse

Returns the status of monitored subsystems.

Name Schema
serviceName
optional
serviceName

serviceName

Name Schema
messages
optional
< string > array
ok
optional
boolean

VersionResponse

Returns the version of Cromwell

Name Description Schema
cromwell
optional
The version of the Cromwell Engine
Example : "30"
string

WorkflowIdAndStatus

Name Description Schema
id
required
The identifier of the workflow
Example : "e442e52a-9de1-47f0-8b4f-e6e565008cf1"
string
status
required
The status of the workflow
Example : "Submitted"
string

WorkflowMetadataResponse

Workflow and call level metadata

Name Description Schema
calls
optional
CallMetadata
end
optional
End datetime of the workflow in ISO8601 format with milliseconds string (date-time)
failures
optional
FailureMessage
id
required
The identifier of the workflow string
inputs
optional
Map of input keys to input values object
outputs
optional
Map of output keys to output values object
start
optional
Start datetime of the workflow in ISO8601 format with milliseconds string (date-time)
status
required
The status of the workflow string
submission
required
Submission datetime of the workflow in ISO8601 format with milliseconds string (date-time)

WorkflowQueryParameter

Workflow query parameters

Name Description Schema
end
optional
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. string (date-time)
excludeLabelAnd
optional
Excludes workflows with the specified label. If specified multiple times, excludes workflows with all of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value"
Pattern : "^([a-z][-a-z0-9]*[a-z0-9])?[:]([a-z][-a-z0-9]*[a-z0-9])?$"
string (array)
excludeLabelOr
optional
Excludes workflows with the specified label. If specified multiple times, excludes workflows with any of the specified label keys. Specify the label key and label value pair as separated with "label-key:label-value"
Pattern : "^([a-z][-a-z0-9]*[a-z0-9])?[:]([a-z][-a-z0-9]*[a-z0-9])?$"
string (array)
id
optional
Returns only workflows with the specified workflow id. If specified multiple times, returns workflows with any of the specified workflow ids.
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}$"
string
includeSubworkflows
optional
Include subworkflows in results. By default, it is taken as true. string (boolean)
name
optional
Returns only workflows with the specified name. If specified multiple times, returns workflows with any of the specified names.
Pattern : "^[a-zA-Z][a-zA-Z0-9_]*$"
string
start
optional
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. string (date-time)
status
optional
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)
submission
optional
Returns only workflows with an equal or later submission time. Can be specified at most once. If both submission time and start date are specified, submission time should be before or equal to start date. string (date-time)

WorkflowQueryResponse

Response to a workflow query

Name Schema
results
required
< WorkflowQueryResult > array
totalResultsCount
required
integer

WorkflowQueryResult

Result for an individual workflow returned by a workflow query

Name Description Schema
end
optional
Workflow end datetime string (date-time)
id
required
Workflow ID string
name
required
Workflow name string
start
optional
Workflow start datetime string (date-time)
status
required
Workflow status string
submission
optional
Workflow submission datetime string (date-time)

WorkflowSubmitResponse

Name Description Schema
id
required
The identifier of the workflow
Example : "e442e52a-9de1-47f0-8b4f-e6e565008cf1"
string
status
required
The status of the workflow
Example : "Submitted"
string