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

Run workflow

POST /api/ga4gh/wes/v1/runs

Description

This endpoint creates a new workflow run and returns a RunId to monitor its progress.

The workflow_attachment array may be used to upload files that are required to execute the workflow, including the primary workflow, tools imported by the workflow, other files referenced by the workflow, or files which are part of the input. The implementation should stage these files to a temporary directory and execute the workflow from there. These parts must have a Content-Disposition header with a "filename" provided for each part. Filenames may include subdirectories, but must not include references to parent directories with '..' -- implementations should guard against maliciously constructed filenames.

The workflow_url is either an absolute URL to a workflow file that is accessible by the WES endpoint, or a relative URL corresponding to one of the files attached using workflow_attachment.

The workflow_params JSON object specifies input parameters, such as input files. The exact format of the JSON object depends on the conventions of the workflow language being used. Input files should either be absolute URLs, or relative URLs corresponding to files uploaded using workflow_attachment. The WES endpoint must understand and be able to access URLs supplied in the input. This is implementation specific.

The workflow_type is the type of workflow language and must be "CWL" or "WDL" currently (or another alternative supported by this WES instance).

The workflow_type_version is the version of the workflow language submitted and must be one supported by this WES instance.

See the RunRequest documentation for details about other fields.

Parameters

Type Name Schema
FormData tags
optional
string
FormData workflow_attachment
optional
< file (binary) > array
FormData workflow_engine_parameters
optional
string
FormData workflow_params
optional
string
FormData workflow_type
optional
string
FormData workflow_type_version
optional
string
FormData workflow_url
optional
string

Responses

HTTP Code Description Schema
201 Successful Request RunId
400 Malformed Workflow ID No Content
401 Invalid submission request No Content
403 Workflow in terminal status No Content
500 Internal Error No Content

Consumes

  • multipart/form-data

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

List runs

GET /api/ga4gh/wes/v1/runs

Description

Runs are listed from newest to oldest. When paging through the list, the client should not make assumptions about live updates, but should assume the contents of the list reflect the workflow list at the moment that the first page is requested. To monitor a specific workflow run, use GetRunStatus or GetRunLog.

Parameters

Type Name Description Schema
Query page_size
optional
OPTIONAL The preferred number of workflow runs to return in a page. If not provided, the implementation should use a default page size. The implementation must not return more items than page_size, but it may return fewer. Clients should not assume that if fewer than page_size items are returned that all items have been returned. The availability of additional pages is indicated by the value of next_page_token in the response. integer (int64)
Query page_token
optional
OPTIONAL Token to use to indicate where to start getting results. If unspecified, return the first page of results. string

Responses

HTTP Code Description Schema
200 Successful Request RunListResponse
400 Malformed Workflow ID No Content
401 Invalid submission request No Content
403 Workflow in terminal status No Content
500 Internal Error No Content

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

Get run log

GET /api/ga4gh/wes/v1/runs/{run_id}

Description

This endpoint provides detailed information about a given workflow run. The returned result has information about the outputs produced by this workflow (if available), a log object which allows the stderr and stdout to be retrieved, a log array so stderr/stdout for individual tasks can be retrieved, and the overall state of the workflow run (e.g. RUNNING, see the State section).

Parameters

Type Name Schema
Path run_id
required
string

Responses

HTTP Code Description Schema
200 Successful Request RunLog
401 Invalid submission request No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

Cancel run

POST /api/ga4gh/wes/v1/runs/{run_id}/cancel

Description

Cancel a running workflow.

Parameters

Type Name Description Schema
Path run_id
required
Run ID string

Responses

HTTP Code Description Schema
200 Successful Request RunId
401 Invalid submission request No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

Get run status

GET /api/ga4gh/wes/v1/runs/{run_id}/status

Description

This provides an abbreviated (and likely fast depending on implementation) status of the running workflow, returning a simple result with the overall state of the workflow run (e.g. RUNNING, see the State section).

Parameters

Type Name Description Schema
Path run_id
required
Run ID string

Responses

HTTP Code Description Schema
200 Successful Request RunStatus
401 Invalid submission request No Content
403 Workflow in terminal status No Content
404 Workflow ID Not Found No Content
500 Internal Error No Content

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

Get service info

GET /api/ga4gh/wes/v1/service-info

Description

May include information related (but not limited to) the workflow descriptor formats, versions supported, the WES API versions supported, and information about general service availability.

Responses

HTTP Code Description Schema
200 Successful Request ServiceInfo
500 Internal Error No Content

Tags

  • GA4GH Workflow Execution Service (WES) - Alpha preview

Machine-readable description of a workflow, including inputs and outputs

POST /api/womtool/{version}/describe

Parameters

Type Name Description Schema Default
Path version
required
Cromwell API Version string "v1"
FormData workflowInputs
optional
JSON or YAML file containing the inputs as an object. file
FormData workflowSource
optional
The workflow source file to submit for execution. Either workflow source or workflow url is required. 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)
FormData workflowUrl
optional
URL which points to the workflow. Either workflow source or workflow url is required. string

Responses

HTTP Code Description Schema
200 Workflow description. WorkflowDescription

Consumes

  • multipart/form-data

Tags

  • Womtool

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 requestedWorkflowId
optional
An ID to ascribe to this workflow. Must be a JSON string in UUID-format. If not supplied a random ID will be generated for the workflow. string
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
optional
The workflow source file to submit for execution. Either workflow source or workflow url is required. 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)
FormData workflowUrl
optional
URL which points to the workflow. Either workflow source or workflow url is required. string

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 requestedWorkflowId
optional
A set of IDs to ascribe to these workflows. Must be a JSON list of strings in UUID-format. Must have the same number of entries and be in the same order as the workflow inputs list. If not supplied, random ID will be generated for the workflows. string
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
optional
The workflow source file to submit for execution. Either workflow source or workflow url is required. 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)
FormData workflowUrl
optional
URL which points to the workflow. Either workflow source or workflow url is required. string

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
Currently only 'labels' is a valid value here. Use it to include a list of labels with each result. < 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 schedule a halt of all 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, filters metadata to not return any field with a name which begins with this value. This key is used relative to the root of the response and relative to each call's metadata fields. Use 'calls' to filter out all call level metadata. < string > array(multi)
Query expandSubWorkflows
optional
When true, metadata for sub workflows will be fetched and inserted automatically in the metadata response. boolean
Query includeKey
optional
When specified, filters metadata to only return fields with names which begins with this value. This key is used relative to the root of the response and relative to each call's metadata fields. < 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

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

DefaultWorkflowEngineParameter

A message that allows one to describe default parameters for a workflow engine.

Name Description Schema
default_value
optional
The stringified version of the default parameter. e.g. "2.45". string
name
optional
The name of the parameter string
type
optional
Describes the type of the parameter, e.g. float. string

DescriptorType

One from a list of descriptor type strings (e.g. CWL, WDL). Note that these files can also include associated Docker/container files and test parameters that further describe a version of a tool

Type : enum (CWL, WDL)

DescriptorTypeAndVersion

A workflow descriptor file type and version.

Name Description Schema
descriptorType
required
DescriptorType
descriptorTypeVersion
required
Example : "1.0" 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

Log

Log and other info

Name Description Schema
cmd
optional
The command line that was executed < string > array
end_time
optional
When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ" string
exit_code
optional
Exit code of the program integer (int32)
name
optional
The task or workflow name string
start_time
optional
When the command started executing, in ISO 8601 format "%Y-%m-%dT%H:%M:%SZ" string
stderr
optional
A URL to retrieve standard error logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint. string
stdout
optional
A URL to retrieve standard output logs of the workflow run or task. This URL may change between status requests, or may not be available until the task or workflow has finished execution. Should be available using the same credentials used to access the WES endpoint. string

MapValueType

A type representing a map from one type to another.

Name Schema
keyType
required
ValueType
valueType
required
ValueType

RunId

Name Description Schema
run_id
optional
workflow run ID string

RunListResponse

The service will return a RunListResponse when receiving a successful RunListRequest.

Name Description Schema
next_page_token
optional
A token which may be supplied as page_token in workflow run list request to get the next page of results. An empty string indicates there are no more items to return. string
runs
optional
A list of workflow runs that the service has executed or is executing. The list is filtered to only include runs that the caller has permission to see. < RunStatus > array

RunLog

Name Description Schema
outputs
optional
The outputs from the workflow run. object
request
optional
RunRequest
run_id
optional
workflow run ID string
run_log
optional
Log
state
optional
State
task_logs
optional
The logs, and other key info like timing and exit code, for each step in the workflow run. < Log > array

RunRequest

To execute a workflow, send a run request including all the details needed to begin downloading and executing a given workflow.

Name Description Schema
tags
optional
< string, string > map
workflow_engine_parameters
optional
< string, string > map
workflow_params
optional
REQUIRED The workflow run parameterizations (JSON encoded), including input and output file locations object
workflow_type
optional
REQUIRED The workflow descriptor type, must be "CWL" or "WDL" currently (or another alternative supported by this WES instance) string
workflow_type_version
optional
REQUIRED The workflow descriptor type version, must be one supported by this WES instance string
workflow_url
optional
REQUIRED The workflow CWL or WDL document. When workflow_attachments is used to attach files, the workflow_url may be a relative path to one of the attachments. string

RunStatus

Small description of a workflow run, returned by server during listing

Name Schema
run_id
required
string
state
optional
State

Service

GA4GH service

Name Description Schema
contactUrl
optional
URL of the contact for the provider of this service, e.g. a link to a contact form (RFC 3986 format), or an email (RFC 2368 format).
Example : "mailto:support@example.com"
string (uri)
createdAt
optional
Timestamp describing when the service was first deployed and available (RFC 3339 format)
Example : "2019-06-04T12:58:19Z"
string (date-time)
description
optional
Description of the service. Should be human readable and provide information about the service.
Example : "This service provides..."
string
documentationUrl
optional
URL of the documentation of this service (RFC 3986 format). This should help someone learn how to use your service, including any specifics required to access data, e.g. authentication.
Example : "https://docs.myservice.example.com"
string (uri)
environment
optional
Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Suggested values are prod, test, dev, staging. However this is advised and not enforced.
Example : "test"
string
id
required
Unique ID of this service. Reverse domain name notation is recommended, though not required. The identifier should attempt to be globally unique so it can be used in downstream aggregator services e.g. Service Registry.
Example : "org.ga4gh.myservice"
string
name
required
Name of this service. Should be human readable.
Example : "My project"
string
organization
required
Organization providing the service organization
type
required
ServiceType
updatedAt
optional
Timestamp describing when the service was last updated (RFC 3339 format)
Example : "2019-06-04T12:58:19Z"
string (date-time)
version
required
Version of the service being described. Semantic versioning is recommended, but other identifiers, such as dates or commit hashes, are also allowed. The version should be changed whenever the service is updated.
Example : "1.0.0"
string

organization

Name Description Schema
name
required
Name of the organization responsible for the service
Example : "My organization"
string
url
required
URL of the website of the organization (RFC 3986 format)
Example : "https://example.com"
string (uri)

ServiceInfo

Polymorphism : Composition

Name Description Schema
auth_instructions_url
required
A web page URL with human-readable instructions on how to get an authorization token for use with a specific WES endpoint. string
contactUrl
optional
URL of the contact for the provider of this service, e.g. a link to a contact form (RFC 3986 format), or an email (RFC 2368 format).
Example : "mailto:support@example.com"
string (uri)
createdAt
optional
Timestamp describing when the service was first deployed and available (RFC 3339 format)
Example : "2019-06-04T12:58:19Z"
string (date-time)
default_workflow_engine_parameters
required
Each workflow engine can present additional parameters that can be sent to the workflow engine. This message will list the default values, and their types for each workflow engine. < DefaultWorkflowEngineParameter > array
description
optional
Description of the service. Should be human readable and provide information about the service.
Example : "This service provides..."
string
documentationUrl
optional
URL of the documentation of this service (RFC 3986 format). This should help someone learn how to use your service, including any specifics required to access data, e.g. authentication.
Example : "https://docs.myservice.example.com"
string (uri)
environment
optional
Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Suggested values are prod, test, dev, staging. However this is advised and not enforced.
Example : "test"
string
id
required
Unique ID of this service. Reverse domain name notation is recommended, though not required. The identifier should attempt to be globally unique so it can be used in downstream aggregator services e.g. Service Registry.
Example : "org.ga4gh.myservice"
string
name
required
Name of this service. Should be human readable.
Example : "My project"
string
organization
required
Organization providing the service organization
supported_filesystem_protocols
required
The filesystem protocols supported by this service, currently these may include common protocols using the terms 'http', 'https', 'sftp', 's3', 'gs', 'file', or 'synapse', but others are possible and the terms beyond these core protocols are currently not fixed. This section reports those protocols (either common or not) supported by this WES service. < string > array
supported_wes_versions
required
The version(s) of the WES schema supported by this service < string > array
system_state_counts
required
< string, integer (int64) > map
tags
required
< string, string > map
type
required
ServiceType
updatedAt
optional
Timestamp describing when the service was last updated (RFC 3339 format)
Example : "2019-06-04T12:58:19Z"
string (date-time)
version
required
Version of the service being described. Semantic versioning is recommended, but other identifiers, such as dates or commit hashes, are also allowed. The version should be changed whenever the service is updated.
Example : "1.0.0"
string
workflow_engine_versions
required
< string, string > map
workflow_type_versions
required
< string, WorkflowTypeVersion > map

organization

Name Description Schema
name
required
Name of the organization responsible for the service
Example : "My organization"
string
url
required
URL of the website of the organization (RFC 3986 format)
Example : "https://example.com"
string (uri)

ServiceType

Type of a GA4GH service

Name Description Schema
artifact
required
Name of the API or GA4GH specification implemented. Official GA4GH types should be assigned as part of standards approval process. Custom artifacts are supported.
Example : "beacon"
string
group
required
Namespace in reverse domain name format. Use org.ga4gh for implementations compliant with official GA4GH specifications. For services with custom APIs not standardized by GA4GH, or implementations diverging from official GA4GH specifications, use a different namespace (e.g. your organization's reverse domain name).
Example : "org.ga4gh"
string
version
required
Version of the API or specification. GA4GH specifications use semantic versioning.
Example : "1.0.0"
string

State

  • UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.

  • QUEUED: The task is queued.

  • INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.

  • RUNNING: The task is running. Input files are downloaded and the first Executor has been started.

  • PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.

  • COMPLETE: The task has completed running. Executors have exited without error and output files have been successfully uploaded.

  • EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally, this means that an Executor exited with a non-zero exit code.

  • SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor, for example an upload failed due to network issues, the worker's ran out of disk space, etc.

  • CANCELED: The task was canceled by the user.

  • CANCELING: The task was canceled by the user, and is in the process of stopping.

Type : enum (UNKNOWN, QUEUED, INITIALIZING, RUNNING, PAUSED, COMPLETE, EXECUTOR_ERROR, SYSTEM_ERROR, CANCELED, CANCELING)

StatusResponse

Returns the status of monitored subsystems.

Name Schema
serviceName
optional
serviceName

serviceName

Name Schema
messages
optional
< string > array
ok
optional
boolean

ToolInputParameter

An input parameter for a tool or workflow.

Name Description Schema
default
required
The in-language expression used to evaluate a default value for this parameter, if none is supplied. string
name
required
The name of this input value (formatted as expected by the tool) string
optional
required
Whether the tool allows this value to not be specified boolean
typeDisplayName
required
An easy-to-read display name for the type of the input string
valueType
required
ValueType

ToolOutputParameter

An output parameter for a tool or workflow.

Name Description Schema
name
required
The name of this input value (formatted as expected by the tool) string
typeDisplayName
required
An easy-to-read display name for the type of the output string
valueType
required
ValueType

ValueType

The type expected for a given value.

Name Description Schema
arrayType
optional
ValueType
mapType
optional
MapValueType
objectFieldTypes
optional
< objectFieldTypes > array
optionalType
optional
ValueType
tupleTypes
optional
< ValueType > array
typeName
optional
The type of this value enum (String, File, Directory, Float, Int, Boolean, Optional, Array, Tuple, Map, Object, Pair)

objectFieldTypes

Name Schema
fieldName
optional
string
fieldType
optional
ValueType

VersionResponse

Returns the version of Cromwell

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

WorkflowDescription

Name Description Schema
errors
required
The set of validation failure messages
Example : [ "The 'errors' field will be filled if 'valid' is false", "We might also provide warnings to a 'valid' workflow here", "Otherwise, 'errors' will be the empty array" ]
< string > array
inputs
required
A list of inputs for this tool
Example : [ {<br> "name" : "my_wf.string_input",<br> "valueType" : {<br> "typeName" : "String"<br> },<br> "optional" : false,<br> "default" : null,<br> "typeDisplayName" : "String"<br>}, {<br> "name" : "my_wf.array_input",<br> "valueType" : {<br> "typeName" : "Array",<br> "arrayType" : {<br> "typeName" : "String"<br> }<br> },<br> "optional" : false,<br> "default" : null,<br> "typeDisplayName" : "Array[String]"<br>}, {<br> "name" : "my_wf.optional_input",<br> "valueType" : {<br> "typeName" : "Optional",<br> "optionalType" : {<br> "typeName" : "String"<br> }<br> },<br> "optional" : true,<br> "default" : "hello",<br> "typeDisplayName" : "String?"<br>}, {<br> "name" : "my_wf.map_input",<br> "valueType" : {<br> "typeName" : "Map",<br> "mapType" : {<br> "keyType" : {<br> "typeName" : "String"<br> },<br> "valueType" : {<br> "typeName" : "Int"<br> }<br> }<br> },<br> "optional" : false,<br> "default" : null,<br> "typeDisplayName" : "Map[String, Int]"<br>}, {<br> "name" : "my_wf.object_input",<br> "valueType" : {<br> "typeName" : "Object",<br> "objectFieldTypes" : [ {<br> "fieldName" : "int_field",<br> "fieldType" : {<br> "typeName" : "Int"<br> }<br> }, {<br> "fieldName" : "int_array_field",<br> "fieldType" : {<br> "typeName" : "Array",<br> "arrayType" : {<br> "typeName" : "Int"<br> }<br> }<br> } ]<br> },<br> "optional" : false,<br> "default" : null,<br> "typeDisplayName" : "Object"<br>}, {<br> "name" : "my_wf.int_string_pair_input",<br> "valueType" : {<br> "typeName" : "Pair",<br> "pairTypes" : [ {<br> "leftType" : [ {<br> "typeName" : "Int"<br> } ]<br> }, {<br> "rightType" : [ {<br> "typeName" : "String"<br> } ]<br> } ]<br> },<br> "optional" : false,<br> "default" : null,<br> "typeDisplayName" : "Pair[Int, String]"<br>} ]
< ToolInputParameter > array
isRunnableWorkflow
required
Indicates whether this file can be run on its own (e.g. a WDL workflow) boolean
name
required
For a source file with one workflow and zero or more tasks, the name of the workflow. For a single task, the name of the task. For a source file with multiple tasks but no workflows, the empty string. string
outputs
required
A list of outputs for this tool
Example : [ {<br> "name" : "my_wf.string_output",<br> "valueType" : {<br> "typeName" : "String"<br> },<br> "typeDisplayName" : "String"<br>}, {<br> "name" : "my_wf.array_output",<br> "valueType" : {<br> "typeName" : "Array",<br> "arrayType" : {<br> "typeName" : "String"<br> }<br> },<br> "typeDisplayName" : "Array[String]"<br>}, {<br> "name" : "my_wf.map_output",<br> "valueType" : {<br> "typeName" : "Map",<br> "mapType" : {<br> "keyType" : {<br> "typeName" : "String"<br> },<br> "valueType" : {<br> "typeName" : "Int"<br> }<br> }<br> },<br> "typeDisplayName" : "Map[String, Int]"<br>}, {<br> "name" : "my_wf.object_output",<br> "valueType" : {<br> "typeName" : "Object",<br> "objectFieldTypes" : [ {<br> "fieldName" : "int_field",<br> "fieldType" : {<br> "typeName" : "Int"<br> }<br> }, {<br> "fieldName" : "int_array_field",<br> "fieldType" : {<br> "typeName" : "Array",<br> "arrayType" : {<br> "typeName" : "Int"<br> }<br> }<br> } ]<br> },<br> "typeDisplayName" : "Object"<br>}, {<br> "name" : "my_wf.int_string_pair_output",<br> "valueType" : {<br> "typeName" : "Pair",<br> "tupleTypes" : [ {<br> "typeName" : "Int"<br> }, {<br> "typeName" : "String"<br> } ]<br> },<br> "typeDisplayName" : "Pair[Int, String]"<br>} ]
< ToolOutputParameter > array
submittedDescriptorType
required
DescriptorTypeAndVersion
valid
required
Indicates that the workflow is valid and that the inputs, if provided, are compatible with the workflow. boolean
validWorkflow
required
Indicates whether the workflow file is valid by itself. If inputs are provided, they are not considered when calculating this field; if inputs are not provided, the value is identical to valid. boolean

WorkflowIdAndStatus

Name Description Schema
id
required
The identifier of the workflow
Example : "00001111-2222-3333-aaaa-bbbbccccdddd"
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
page
optional
When pageSize is set, which page of results to return. If not set, the first page of 'pageSize' results will be returned. integer
pageSize
optional
The number of results to return at a time integer
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
metadataArchiveStatus
optional
Status in metadata archives string
name
optional
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 : "00001111-2222-3333-aaaa-bbbbccccdddd"
string
status
required
The status of the workflow
Example : "Submitted"
string

WorkflowTypeVersion

Available workflow types supported by a given instance of the service.

Name Description Schema
workflow_type_version
optional
an array of one or more acceptable types for the workflow_type < string > array