Create Workflow Definition

Endpoint: POST /api/metadata/workflow

Creates a new workflow definition.

Query parameters

Parameter	Description	Type	Required/ Optional
overwrite	Whether to overwrite the existing definition with the same name. Default is false. Set to true to overwrite an existing definition.	boolean	Optional.
newVersion	Whether to create a new version for the workflow definition. Default is false. Set to true to create a new version.	boolean	Optional.

Request body

Parameter	Description	Type	Required/ Optional
name	A unique name for the workflow definition. For v4.0.1 and prior: Only letters, digits, hyphens (-), and underscores (_) are allowed. For v4.0.2 and later: Only letters, digits, spaces, hyphens (-), underscores (_), and certain special characters (<, >, {, }, #) are allowed. Note: It is recommended to use alphanumeric characters for workflow names. While special characters are allowed for backward compatibility, they are not fully supported and may cause unexpected behavior.	string	Required.
description	A description of the workflow.	string	Optional.
version	The version of the workflow definition. Defaults to 0 if not specified.	integer	Optional.
tasks	The task configurations to be included in the workflow.	array of objects	Required.
inputParameters	The input keys for the workflow.	array of strings	Optional.
outputParameters	The JSON template used to generate the workflow output. If unspecified, the workflow output is defined as the output of the last executed task.	object	Optional.
enforceSchema	Whether to enforce input schema validation. Set to true to enable validation or false to disable.	boolean	Optional.
inputSchema	The schema to be used as the input schema for the workflow definition. Learn more about creating and using schemas.	object	Required if enforceSchema is set to true.
outputSchema	The schema to be used as the output schema for the workflow definition. Learn more about creating and using schemas.	object	Required if enforceSchema is set to true.
restartable	Whether the workflow can be restarted after completion. Set to false if restarting could impact workflow functionality.	boolean	Optional.
timeoutSeconds	The timeout, in seconds, after which the workflow will be set as TIMED_OUT if it hasn't reached a terminal state. No timeout occurs if the value is set to 0.	integer	Required.
timeoutPolicy	The policy for handling workflow timeout. Supported values: TIME_OUT_WF-The workflow is set to TIMED_OUT and is terminated. ALERT_ONLY-Increments the counter to check the workflow status when it times out and logs relevant messages.	string	Optional.
failureWorkflow	The compensation workflow to trigger upon failure of the current workflow execution.	string	Optional.
workflowStatusListenerEnabled	Whether to enable status callback for workflow state changes. Learn more about enabling CDC.	boolean	Optional.
workflowStatusListenerSink	The sink where workflow state changes are sent.	string	Required if workflowStatusListener is set to true.
rateLimitConfig	A map of the workflow rate limit configuration.	object	Optional.
rateLimitConfig. rateLimitKey	A unique identifier to group workflow executions for rate limits. Can be a fixed value (for example, "max") or a dynamic variable from the workflow input (for example, ${workflow.input.correlationId}).	string	Optional.
rateLimitConfig. concurrentExecLimit	The number of workflow executions that can run concurrently for each rate limit key. Cannot be passed as a dynamic variable.	integer	Optional.
maskedFields	The fields to mask in the workflow execution.	array of strings	Optional.
tags	A key-value map to add tags to the workflow definition. Each tag consists of a key associated with a corresponding value.	object	Optional.
schemaVersion	The current version of the Conductor schema. Must be 2.	integer	Required.
ownerEmail	The email address of the user creating the workflow definition.	string	Required.

Response

Returns 200 OK, indicating that the workflow definition has been created successfully.

Examples

Create a new workflow definition

Request

curl -X 'POST' \
  'https://<YOUR_CLUSTER>/api/metadata/workflow?overwrite=false&newVersion=false' \
  -H 'accept: */*' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "api-test",
  "description": "Sample workflow created using API",
  "version": 1,
  "tasks": [
    {
      "name": "event",
      "taskReferenceName": "event_ref",
      "type": "EVENT",
      "sink": "sqs:internal_event_name",
      "inputParameters": {}
    }
  ],
  "inputParameters": [],
  "outputParameters": {},
  "schemaVersion": 2,
  "restartable": true,
  "workflowStatusListenerEnabled": false,
  "ownerEmail": "john.doe@acme.com",
  "timeoutPolicy": "ALERT_ONLY",
  "timeoutSeconds": 0
}'

Response

Returns 200 OK, indicating that the workflow definition has been created successfully.

Create a new workflow definition with newVersion set to true

Request

curl -X 'POST' \
  'https://<YOUR-CLUSTER>/api/metadata/workflow?overwrite=false&newVersion=true' \
  -H 'accept: */*' \
  -H 'X-Authorization: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "api-test",
  "description": "Sample workflow created using API",
  "version": 1,
  "tasks": [
    {
      "name": "event",
      "taskReferenceName": "event_ref",
      "type": "EVENT",
      "sink": "sqs:internal_event_name",
      "inputParameters": {}
    }
  ],
  "inputParameters": [],
  "outputParameters": {},
  "schemaVersion": 2,
  "restartable": true,
  "workflowStatusListenerEnabled": false,
  "ownerEmail": "john.doe@acme.com",
  "timeoutPolicy": "ALERT_ONLY",
  "timeoutSeconds": 0
}
'

Response

Returns 200 OK, indicating that the new workflow version has been created successfully.