> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for Compozy tasks, including all task types, configurations, and event handlers.

## JSON Schema

```json https://compozy.dev/schemas/tasks.json [expandable] theme={"dark"}
{
  "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

<ParamField path="id" type="string" required>
  Unique identifier for the task within the workflow
</ParamField>

<ParamField path="name" type="string">
  Human-readable name for the task
</ParamField>

<ParamField path="type" type="string" required>
  Task type identifier. One of: `basic`, `parallel`, `decision`, `collection`, `wait`, `map`, `composite`. See [Task Types](/core/tasks/types) for detailed information about each type.
</ParamField>

<ParamField path="use" 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

  <CodeGroup>
    ```yaml Shorthand theme={"dark"}
    tasks:
      - id: web_search
        type: basic
        use: compozy/tasks:web-search
    ```

    ```yaml Version theme={"dark"}
    tasks:
      - id: pdf_reader
        type: basic
        use: compozy/tasks:pdf-reader@1.0.0
    ```

    ```yaml Detailed theme={"dark"}
    tasks:
      - id: data_processor
        type: basic
        use:
          repo: compozy/tasks
          package: data-processor
          version: 2.1.0
    ```
  </CodeGroup>
</ParamField>

<ParamField path="import" type="string">
  Path to external task definition file. Can be a local file path or a package reference.
</ParamField>

<ParamField path="schema" type="object">
  Schema definition for task input validation

  <Expandable title="Schema Properties">
    <ParamField path="input" type="object">
      JSON Schema for task input validation
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="config" type="object">
  Task type-specific configuration

  <Expandable title="Type-specific Configurations">
    <ParamField path="basic" type="object">
      <Expandable title="Properties">
        <ParamField path="timeout" type="string">
          Operation timeout duration
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="parallel" type="object">
      <Expandable title="Properties">
        <ParamField path="max_concurrent" type="number">
          Maximum number of concurrent operations
        </ParamField>

        <ParamField path="fail_fast" type="boolean">
          Whether to stop all operations if one fails
        </ParamField>

        <ParamField path="timeout" type="string">
          Operation timeout duration
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="decision" type="object">
      <Expandable title="Properties">
        <ParamField path="condition" type="string">
          Decision condition expression
        </ParamField>

        <ParamField path="routes" type="object">
          Route mapping for different conditions
        </ParamField>

        <ParamField path="default" type="object">
          Default route configuration
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="collection" type="object">
      <Expandable title="Properties">
        <ParamField path="mode" type="string">
          Processing mode: `parallel` or `sequential`
        </ParamField>

        <ParamField path="batch_size" type="number">
          Number of items to process in each batch
        </ParamField>

        <ParamField path="max_concurrent" type="number">
          Maximum concurrent batches
        </ParamField>

        <ParamField path="continue_on_error" type="boolean">
          Whether to continue processing on item failure
        </ParamField>

        <ParamField path="timeout_per_batch" type="string">
          Timeout duration for each batch
        </ParamField>

        <ParamField path="timeout_per_item" type="string">
          Timeout duration for each item
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="wait" type="object">
      <Expandable title="Properties">
        <ParamField path="timeout" type="string" required>
          Maximum wait duration
        </ParamField>

        <ParamField path="check_interval" type="string" required>
          Interval between condition checks
        </ParamField>

        <ParamField path="max_checks" type="number">
          Maximum number of condition checks
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="map" type="object">
      <Expandable title="Properties">
        <ParamField path="validate_schema" type="boolean">
          Whether to validate mapping against schema
        </ParamField>

        <ParamField path="strict_mode" type="boolean">
          Whether to enforce strict type checking
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="composite" type="object">
      <Expandable title="Properties">
        <ParamField path="error_handling" type="string">
          Error handling mode: `continue` or `stop`
        </ParamField>

        <ParamField path="timeout" type="string">
          Overall timeout for all subtasks
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="retry" type="object">
  Retry configuration for failed tasks

  <Expandable title="Properties">
    <ParamField path="attempts" type="number" required>
      Maximum number of retry attempts
    </ParamField>

    <ParamField path="backoff" type="string" required>
      Backoff strategy: `fixed`, `exponential`, or `linear`
    </ParamField>

    <ParamField path="interval" type="string" required>
      Initial retry interval (e.g., "1s", "5m")
    </ParamField>

    <ParamField path="max_interval" type="string">
      Maximum retry interval
    </ParamField>

    <ParamField path="jitter" type="boolean">
      Whether to add randomness to retry intervals
    </ParamField>
  </Expandable>
</ParamField>

### Event Handlers

<ParamField path="on_start" type="object">
  Handler called when task starts

  <Expandable title="Properties">
    <ParamField path="next" type="string">
      Next task to execute
    </ParamField>

    <ParamField path="with" type="object">
      Data to pass to next task
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="on_success" type="object">
  Handler called when task succeeds

  <Expandable title="Properties">
    <ParamField path="next" type="string">
      Next task to execute
    </ParamField>

    <ParamField path="with" type="object">
      Data to pass to next task
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="on_error" type="object">
  Handler called when task fails

  <Expandable title="Properties">
    <ParamField path="next" type="string">
      Next task to execute
    </ParamField>

    <ParamField path="with" type="object">
      Data to pass to next task
    </ParamField>

    <ParamField path="condition" type="string">
      Error condition expression
    </ParamField>

    <ParamField path="routes" type="object">
      Conditional error routing
    </ParamField>

    <ParamField path="retry" type="boolean">
      Whether to retry the task
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="on_complete" type="object">
  Handler called after task completes (success or error)

  <Expandable title="Properties">
    <ParamField path="next" type="string">
      Next task to execute
    </ParamField>

    <ParamField path="with" type="object">
      Data to pass to next task
    </ParamField>
  </Expandable>
</ParamField>

### Type-specific Event Handlers

<ParamField path="collection" type="object">
  Collection task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_item_start" type="object">
      Called when item processing starts
    </ParamField>

    <ParamField path="on_item_success" type="object">
      Called when item processing succeeds
    </ParamField>

    <ParamField path="on_item_error" type="object">
      Called when item processing fails
    </ParamField>

    <ParamField path="on_batch_start" type="object">
      Called when batch processing starts
    </ParamField>

    <ParamField path="on_batch_complete" type="object">
      Called when batch processing completes
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="parallel" type="object">
  Parallel task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_operation_start" type="object">
      Called when operation starts
    </ParamField>

    <ParamField path="on_operation_complete" type="object">
      Called when operation completes
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="decision" type="object">
  Decision task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_condition_match" type="object">
      Called when a condition matches
    </ParamField>

    <ParamField path="on_condition_nomatch" type="object">
      Called when no conditions match
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="wait" type="object">
  Wait task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_check" type="object">
      Called on each condition check
    </ParamField>

    <ParamField path="on_timeout" type="object">
      Called when wait timeout is reached
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="map" type="object">
  Map task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_validation_error" type="object">
      Called when schema validation fails
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="composite" type="object">
  Composite task specific handlers

  <Expandable title="Event Handlers">
    <ParamField path="on_task_start" type="object">
      Called when subtask starts
    </ParamField>

    <ParamField path="on_task_complete" type="object">
      Called when subtask completes
    </ParamField>
  </Expandable>
</ParamField>

## State Information

<ParamField path="status" type="string">
  Current task status: `running`, `success`, or `error`
</ParamField>

<ParamField path="duration" type="number">
  Task execution duration in milliseconds
</ParamField>

<ParamField path="start_time" type="string">
  ISO timestamp of when task started
</ParamField>

<ParamField path="end_time" type="string">
  ISO timestamp of when task completed
</ParamField>

<ParamField path="retry_count" type="number">
  Number of retry attempts made
</ParamField>

<ParamField path="error" type="object">
  Error information if task failed

  <Expandable title="Properties">
    <ParamField path="code" type="string">
      Error code identifier
    </ParamField>

    <ParamField path="message" type="string">
      Human-readable error message
    </ParamField>

    <ParamField path="details" type="any">
      Additional error details
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="output" type="any">
  Task output data
</ParamField>

## Expression Context

<ParamField path="id" type="string">
  Current task ID
</ParamField>

<ParamField path="type" type="string">
  Task type
</ParamField>

<ParamField path="status" type="string">
  Task status
</ParamField>

<ParamField path="input" type="any">
  Task input data
</ParamField>

<ParamField path="output" type="any">
  Task output data
</ParamField>

<ParamField path="error" type="any">
  Error information
</ParamField>

<ParamField path="tasks" type="object">
  Access to other task data

  <Expandable title="Task Reference">
    <ParamField path="[taskId].output" type="any">
      Task output data
    </ParamField>

    <ParamField path="[taskId].error" type="any">
      Task error information
    </ParamField>

    <ParamField path="[taskId].status" type="string">
      Task status
    </ParamField>

    <ParamField path="[taskId].duration" type="number">
      Task duration
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="now()" type="function">
  Returns current timestamp
</ParamField>

<ParamField path="env" type="object">
  Environment variables
</ParamField>

### Type-specific Context

<ParamField path="item" type="any">
  Current item in collection task
</ParamField>

<ParamField path="index" type="number">
  Current index in collection task
</ParamField>

<ParamField path="batch_index" type="number">
  Current batch index in collection task
</ParamField>

<ParamField path="operation_id" type="string">
  Current operation ID in parallel task
</ParamField>