engine9 Task API

The engine9 Task API schedules predefined flows and on-demand worker methods over HTTP, then exposes asynchronous flow and task run state. Use this skill for scripts, curl, and integrations, or when troubleshooting direct-HTTP authentication, account scoping, scheduling, and run state.

Quick reference

Rule: Do not mix Task API key authentication with MCP session authentication.

Concepts

Pick the endpoint that matches the work. They both call scheduleTasks and return flow_run_id / task_run_ids.

An on-demand task does not need a flow_id. A predefined flow does not need path or method — those come from the flow definition. Do not send flow_id to /tasks/schedule.

On-demand names (REST and MCP): built-in engine9 Workers use @engine9/plugins/e9workers:<Worker> — no plugin-id lookup. Echo smoke test: path: "@engine9/plugins/e9workers:EchoWorker", method: "echo". See echo-walkthrough.md.

Routes live at the API origin root (/flows, /tasks/schedule, /task_runs/filter, /flow_runs/, …), not under /api/task. Read operations require tasks:read; scheduling and control operations require tasks:schedule. Requests do not block until execution finishes, so poll POST /task_runs/filter until terminal. completed_since on flow runs is computed from timestamps (last_completed ≤ dataflow_last_completed; equal is true) as described in concepts.md.

Rule: Use POST /flow_runs/ only for a published flow_id, and use POST /tasks/schedule only for an on-demand path plus method.

Examples

Follow echo-walkthrough.md end to end: ask the user for an account id and e9key_ API key (offer the default base URL https://data.engine9.ai), then schedule the Echo task, poll until it completes, and report the output — explaining each call and each response as you go. Never print the full API key.

Workflow

1. Discover flows — GET /flows (or POST /flows/filter) lists published slugs; GET /flows/:id shows each step's task_key and default options
2. POST /flow_runs/filter with {"limit":20} — list recent remote runs for the account (default remote: true; no flow_run_id). Add "flow_id": "<dataflow_id>" for runs of one remote dataflow (endpoints.md). For totals and FAILED / RUNNING / COMPLETED pills, POST /flow_runs/count and POST /flow_runs/metrics with the same filters (omit status on metrics so pills ignore the current state filter).
3. Schedule — pick the matching endpoint:
   • On-demand task: POST /tasks/schedule with { "path": "@engine9/plugins/e9workers:EchoWorker", "method": "echo", "options"? }. Built-in workers: @engine9/plugins/e9workers:<Worker> (no plugin lookup). Account plugins: path from discovery, then this endpoint. Optional flow-run tags (Prefect name for Frakture tracking_code, one string). See also POST /flow_runs/.
   • Predefined flow: GET /flows then POST /flow_runs/ with { "flow_id": "<slug>", "options"? } — optional top-level options (e.g. start / end) merges into every step; optional tasks: [{ task_key, options }] for per-step overrides. flow_id is required. Optional tags same as on-demand (not flow-definition tags). See also POST /tasks/schedule. → save flow_run_id / task_run_ids
4. POST /task_runs/filter — { "flow_run_id": "…" } until complete (each task_run includes log_link; no checkpoints)
5. Remote output: GET /task_runs/:id (output, resolved_options, checkpoints) or GET /task_runs/:id/output. Logs: GET /task_runs/:id/log (log, truncated, optional log_url). Per-task Run now: POST /task_runs/:id/retry. Checkpoints are worker-written option snapshots (a task can have multiple, oldest first) and appear only on this single-task read — not on POST /task_runs/filter. Retry does not clear them. To RESET ALL or walk back the most recent checkpoint(s), POST /task_runs/:id/reset_checkpoints { start_index? } (0 / omitted clears all; N keeps the first N). You cannot yank a checkpoint out of the middle.

Full curl: echo-walkthrough.md.

Endpoints

Details: endpoints.md.

Troubleshooting

Full list: errors.md.

Related documentation