API Reference

JSON Schema

https://compozy.dev/schemas/tasks.json

{
  "type": "object",
  "required": ["tasks"],
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "type"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the task"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the task"
          },
          "type": {
            "type": "string",
            "enum": ["basic", "parallel", "decision", "collection", "wait", "map", "composite"],
            "description": "Task type identifier"
          },
          "use": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "required": ["repo", "package"],
                "properties": {
                  "repo": { "type": "string" },
                  "package": { "type": "string" },
                  "version": { "type": "string" }
                }
              }
            ],
            "description": "Task implementation reference"
          },
          "import": {
            "type": "string",
            "description": "Path to external task definition file"
          },
          "schema": {
            "type": "object",
            "properties": {
              "input": { "type": "object" }
            },
            "description": "Schema definition for task input validation"
          },
          "config": {
            "oneOf": [
              { "$ref": "https://compozy.dev/schemas/task-basic.json" },
              { "$ref": "https://compozy.dev/schemas/task-parallel.json" },
              { "$ref": "https://compozy.dev/schemas/task-decision.json" },
              { "$ref": "https://compozy.dev/schemas/task-collection.json" },
              { "$ref": "https://compozy.dev/schemas/task-wait.json" },
              { "$ref": "https://compozy.dev/schemas/task-map.json" },
              { "$ref": "https://compozy.dev/schemas/task-composite.json" }
            ],
            "description": "Task type-specific configuration"
          },
          "retry": {
            "type": "object",
            "required": ["attempts", "backoff", "interval"],
            "properties": {
              "attempts": { "type": "number" },
              "backoff": {
                "type": "string",
                "enum": ["fixed", "exponential", "linear"]
              },
              "interval": { "type": "string" },
              "max_interval": { "type": "string" },
              "jitter": { "type": "boolean" }
            }
          },
          "on_start": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          },
          "on_success": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          },
          "on_error": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" },
              "condition": { "type": "string" },
              "routes": { "type": "object" },
              "retry": { "type": "boolean" }
            }
          },
          "on_complete": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Task Configuration

Properties

string

required

Unique identifier for the task within the workflow

string

Human-readable name for the task

string

required

Task type identifier. One of: basic, parallel, decision, collection, wait, map, composite. See Task Types for detailed information about each type.

string | object

Task implementation reference. Can be specified in three formats:

"repo/package" (e.g., "compozy/tasks:web-search")
"repo:package@version" (e.g., "compozy/tasks:web-search@1.0.0")
Object with repo and package fields

tasks:
  - id: web_search
    type: basic
    use: compozy/tasks:web-search

tasks:
  - id: pdf_reader
    type: basic
    use: compozy/tasks:pdf-reader@1.0.0

tasks:
  - id: data_processor
    type: basic
    use:
      repo: compozy/tasks
      package: data-processor
      version: 2.1.0

string

Path to external task definition file. Can be a local file path or a package reference.

object

Schema definition for task input validation

Show Schema Properties

object

JSON Schema for task input validation

object

Task type-specific configuration

Show Type-specific Configurations

object

Show Properties

string

Operation timeout duration

object

Show Properties

number

Maximum number of concurrent operations

boolean

Whether to stop all operations if one fails

string

Operation timeout duration

object

Show Properties

string

Decision condition expression

object

Route mapping for different conditions

object

Default route configuration

object

Show Properties

string

Processing mode: parallel or sequential

number

Number of items to process in each batch

number

Maximum concurrent batches

boolean

Whether to continue processing on item failure

string

Timeout duration for each batch

string

Timeout duration for each item

object

Show Properties

string

required

Maximum wait duration

string

required

Interval between condition checks

number

Maximum number of condition checks

object

Show Properties

boolean

Whether to validate mapping against schema

boolean

Whether to enforce strict type checking

object

Show Properties

string

Error handling mode: continue or stop

string

Overall timeout for all subtasks

object

Retry configuration for failed tasks

Show Properties

number

required

Maximum number of retry attempts

string

required

Backoff strategy: fixed, exponential, or linear

string

required

Initial retry interval (e.g., “1s”, “5m”)

string

Maximum retry interval

boolean

Whether to add randomness to retry intervals

Event Handlers

object

Handler called when task starts

Show Properties

string

Next task to execute

object

Data to pass to next task

object

Handler called when task succeeds

Show Properties

string

Next task to execute

object

Data to pass to next task

object

Handler called when task fails

Show Properties

string

Next task to execute

object

Data to pass to next task

string

Error condition expression

object

Conditional error routing

boolean

Whether to retry the task

object

Handler called after task completes (success or error)

Show Properties

string

Next task to execute

object

Data to pass to next task

Type-specific Event Handlers

object

Collection task specific handlers

Show Event Handlers

object

Called when item processing starts

object

Called when item processing succeeds

object

Called when item processing fails

object

Called when batch processing starts

object

Called when batch processing completes

object

Parallel task specific handlers

Show Event Handlers

object

Called when operation starts

object

Called when operation completes

object

Decision task specific handlers

Show Event Handlers

object

Called when a condition matches

object

Called when no conditions match

object

Wait task specific handlers

Show Event Handlers

object

Called on each condition check

object

Called when wait timeout is reached

object

Map task specific handlers

Show Event Handlers

object

Called when schema validation fails

object

Composite task specific handlers

Show Event Handlers

object

Called when subtask starts

object

Called when subtask completes

State Information

string

Current task status: running, success, or error

number

Task execution duration in milliseconds

string

ISO timestamp of when task started

string

ISO timestamp of when task completed

number

Number of retry attempts made

object

Error information if task failed

Show Properties

string

Error code identifier

string

Human-readable error message

any

Additional error details

any

Task output data

Expression Context

string

Current task ID

string

Task type

string

Task status

any

Task input data

any

Task output data

any

Error information

object

Access to other task data

Show Task Reference

any

Task output data

any

Task error information

string

Task status

number

Task duration

function

Returns current timestamp

object

Environment variables

Type-specific Context

any

Current item in collection task

number

Current index in collection task

number

Current batch index in collection task

string

Current operation ID in parallel task

Getting Started

Core Concepts

JSON Schema

Task Configuration

Properties

Event Handlers

Type-specific Event Handlers

State Information

Expression Context

Type-specific Context

​JSON Schema

​Task Configuration

​Properties

​Event Handlers

​Type-specific Event Handlers

​State Information

​Expression Context

​Type-specific Context

JSON Schema

Task Configuration

Properties

Event Handlers

Type-specific Event Handlers

State Information

Expression Context

Type-specific Context