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

# Definition and API reference

> Use the same workload model as the editor when creating or managing workflows through HTTP. Routes below are relative to your engine's HTTP origin and include the /api/v1 prefix.

ReferenceApplies to: Unified engine deployments

Use the same workload model as the editor when creating or managing workflows through HTTP. Routes below are relative to your engine's HTTP origin and include the `/api/v1` prefix.

For editable requests and a complete linked example, use [Create and run a workload over HTTP](https://docs.e6data.com/transformation/http/examples/workload.md). The [HTTP API reference](https://docs.e6data.com/transformation/http/reference.md) covers the full API beyond workloads.

## Definition shape

A workload draft contains `name`, `tasks`, `dependencies`, `parameters`, `options`, `policy`, and optional `workflow` settings. The complete definitions in [Your first workload](https://docs.e6data.com/transformation/workloads/first-workload.md) and [Build a multi-task workflow](https://docs.e6data.com/transformation/workloads/multi-task-workflow.md) can be expanded and copied.

For HTTP creation, add a nonnil UUID `submission_id` to the draft. The editor supplies request identities itself. Update and validation requests have their own request fields; do not send a run's response object as a create body.

POST the complete draft plus `submission_id` to `/api/v1/workloads/validate` to validate, or to `/api/v1/workloads` to create. Validation does not save or execute it. For PUT, add both a fresh `submission_id` and the reviewed `expected_revision` to the complete updated definition. Pause and resume requests contain `submission_id` and `expected_revision`.

| Field | Purpose |
| - | - |
| `name` | Workload display name. |
| `tasks` | Named SQL, batch Python, or sensor tasks with initial query settings and optional execution overrides. |
| `dependencies` | Edges containing `upstream`, `downstream`, and nullable `input_name`. |
| `parameters` | Named typed definitions with presence, default, description, and allowed-value rules. |
| `options` | Workload execution and scheduling-behavior defaults. |
| `policy` | Manual, immediate, one-time, interval, or cron schedule. |
| `workflow` | Data-window generation and notification subscriptions. |

## Task fields

| Field | Purpose |
| - | - |
| `name` | Unique stable task name. |
| `sql` | SQL source for a SQL task. |
| `python`, `python_mode` | Python source and `Batch` mode for a batch Python task. |
| `settings` | `current_catalog`, `namespace`, `time_zone`, `case_sensitive`, and `ansi_enabled`. |
| `control.retry` | Optional task retry override. See [Retry policies](https://docs.e6data.com/transformation/workloads/retries.md). |
| `control.sensor` | Optional sensor definition. Sensor tasks do not need SQL. See [Sensors](https://docs.e6data.com/transformation/workloads/sensors.md). |
| Execution overrides | `worker_scope`, `deployment_profile`, `provisioner`, `profile`, or `compute_requirements`. |
| `incremental_source` | Supported table cursor source. See [Incremental workloads](https://docs.e6data.com/transformation/workloads/incremental.md). |

All tasks use the same initial query context. Python uses ordering dependencies without incoming SQL result aliases. A sensor supplies no row result. Graph validation rejects cycles and missing task references.

## Schedule JSON

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"Manual"
```

Other shapes are:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"Immediately"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "At": { "at": { "unix_millis": 1893456000000 } } }
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "Interval": {
    "start_at": { "unix_millis": 1893456000000 },
    "every": { "secs": 300, "nanos": 0 }
  }
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "Cron": { "expression": "0 0 0 * * *", "timezone": "UTC" } }
```

Timestamps use Unix milliseconds. Durations use seconds and nanoseconds. Cron uses a seconds field. Data-window interval boundaries use UTC; cron windows follow the saved schedule time zone.

## Execution options

| Option | Values or meaning |
| - | - |
| `worker_scope` | `Deployment`, `Workload`, or `Task`. |
| `deployment_profile` | A configured deployment compute profile. |
| `provisioner`, `profile` | Available allocation choices for non-deployment compute. |
| `compute_requirements` | CPU millicores, memory bytes, and optional query tuning. |
| `parallelism` | Positive task concurrency limit. |
| `queue_timeout`, `execution_timeout` | Optional durations for their respective phases. |
| `max_attempts` | Positive inherited task attempt limit. |
| `missed_run_policy` | `RunOnce`, `RunAll`, or `Skip`. |
| `overlap_policy` | `Wait`, `Skip`, or `Allow`; incremental workloads reject Allow. |
| `execution_target` | Engine target; native editor examples use `DuckDb` in the API model. |

Omitted choices are resolved from instance defaults. Deployment compute uses its deployment profile rather than a separate provisioner, profile, or custom resource request. Inspect GET `/api/v1/execution-options` for available compute choices.

## Create and manage workloads

| Method | Route | Purpose |
| - | - | - |
| GET / POST | `/api/v1/workloads` | List or create workloads. |
| POST | `/api/v1/workloads/validate` | Validate a definition without executing it. |
| GET / PUT / DELETE | `/api/v1/workloads/{workload_id}` | Read, update, or delete a workload. |
| POST | `/api/v1/workloads/{workload_id}/pause` | Pause new work. |
| POST | `/api/v1/workloads/{workload_id}/resume` | Resume new work under the saved policy. |

## Start and inspect runs

| Method | Route | Purpose |
| - | - | - |
| GET / POST | `/api/v1/workloads/{workload_id}/runs` | List runs or start a manual run. |
| GET | `/api/v1/workloads/{workload_id}/run-summaries` | Read paged run summaries. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}` | Read a run's recorded invocation and state. |
| POST | `/api/v1/workloads/{workload_id}/runs/{run_id}/cancel` | Request cancellation. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}/tasks` | Read tasks. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}` | Read a task. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}/attempts` | Read attempts. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}/attempts/{attempt_id}` | Read one attempt. |

A manual start body contains:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "submission_id": "66666666-6666-4666-8666-666666666666",
  "expected_revision": 1,
  "parameters": { "region": "North", "minimum_amount": 0 }
}
```

Use parameter values defined by that workload. Add `data_window` for a manual windowed invocation; see [Data windows](https://docs.e6data.com/transformation/workloads/data-windows.md). Replace example IDs and revisions with your saved values.

## Reruns, backfills, and notifications

| Method | Route | Purpose |
| - | - | - |
| POST | `/api/v1/workloads/{workload_id}/runs/{run_id}/rerun/preview` | Preview execute, reuse, and blocked tasks. |
| POST | `/api/v1/workloads/{workload_id}/runs/{run_id}/rerun` | Start the reviewed selective rerun. |
| GET / POST | `/api/v1/workloads/{workload_id}/backfills` | List or create backfills. |
| POST | `/api/v1/workloads/{workload_id}/backfills/preview` | Preview historical windows. |
| GET / POST | `/api/v1/workloads/{workload_id}/backfills/{backfill_id}` | Read progress or submit a control action. |
| GET | `/api/v1/workloads/{workload_id}/runs/{run_id}/notifications` | Read delivery history. |
| POST | `/api/v1/workloads/{workload_id}/runs/{run_id}/notifications/retry` | Retry a recorded event's delivery. |

Use the full request examples in [Selective reruns](https://docs.e6data.com/transformation/workloads/reruns.md), [Backfills](https://docs.e6data.com/transformation/workloads/backfills.md), and [Notifications](https://docs.e6data.com/transformation/workloads/notifications.md). For retained query output, see [Results and table commits](https://docs.e6data.com/transformation/workloads/results-and-commits.md).

## Request identity and revisions

A submission ID identifies one intended operation. Retry an identical request with the same ID after a lost response. Use a fresh ID for new intended work. Reusing an ID with changed content can produce a conflict.

`expected_revision` protects operations that depend on a reviewed workload definition. Reload and review if the saved revision changes before acceptance. A successful HTTP acceptance is not proof that execution or publication finished; follow the returned identity to its final status.

## Operator defaults

Service configuration belongs under Operations: [Scheduler](https://docs.e6data.com/transformation/operations/configuration/scheduler.md), [Controller](https://docs.e6data.com/transformation/operations/configuration/controller.md), [Compute](https://docs.e6data.com/transformation/operations/configuration/compute.md), and [Submission defaults](https://docs.e6data.com/transformation/operations/configuration/submission-defaults.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.