API Reference

The Tasked HTTP API lets you manage queues, submit DAG workflows, monitor flow progress, and acknowledge callback tasks.

Base URL: http://localhost:8080 Content-Type: application/json OpenAPI Spec

Sections

System

Health check and Prometheus metrics

Queues

Create, list, get, and delete execution queues

Flows

Submit DAGs, monitor progress, cancel flows, stream events (SSE)

Tasks

Acknowledge callback task completion

Schedules

Create, list, update, and delete cron schedules

Artifacts

Upload, download, and list shared files between tasks

Schemas

Request/response types and enums

Errors

Error codes and response format

System

Health and observability endpoints.

GET /healthz Health check ▶

Returns server health status.

Responses
200 OK
Response
{ "status": "ok" }
GET /metrics Prometheus metrics ▶

Returns metrics in Prometheus text exposition format.

Responses
200 OK

Queues

Queues define execution policies: concurrency limits, retry counts, backoff strategies, and rate limiting. All flows are submitted to a queue.

POST /api/v1/queues Create a queue ▶

Creates a new execution queue. All config fields are optional and default to sensible values.

Request Body
FieldTypeDescription
idrequired string Unique queue identifier
config QueueConfig Execution policy (see schema)
Responses
201 Created 409 Already exists
Request
curl -X POST http://localhost:8080/api/v1/queues \
  -H "Content-Type: application/json" \
  -d '{
  "id": "ci",
  "config": {
    "concurrency": 5,
    "max_retries": 2,
    "rate_limit": {
      "max_burst": 10,
      "per_second": 5.0
    }
  }
}'
Response — 201
{
  "id": "ci",
  "config": {
    "concurrency": 5,
    "max_retries": 2,
    "timeout_secs": 300,
    "backoff": { "Exponential": { "initial_delay_ms": 1000 } },
    "rate_limit": { "max_burst": 10, "per_second": 5.0 }
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}
GET /api/v1/queues List queues ▶

Returns all queues.

Responses
200 OK
Response — 200
[
  {
    "id": "ci",
    "config": { "concurrency": 5, ... },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]
GET /api/v1/queues/{qid} Get queue detail ▶
Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Responses
200 OK 404 Not found
DELETE /api/v1/queues/{qid} Delete a queue ▶

Deletes a queue and all associated flows and tasks.

Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Responses
204 No Content 404 Not found

Flows

A flow is a DAG of tasks submitted to a queue. The engine resolves topological ordering and executes tasks as their dependencies complete.

POST /api/v1/queues/{qid}/flows Submit a flow ▶

Submits a DAG of tasks for execution. Tasks with no depends_on run immediately. Circular dependencies are rejected.

Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Request Body — FlowDef
FieldTypeDescription
tasksrequired TaskDef[] Array of task definitions
webhooks FlowWebhooks? Optional webhook URLs: { on_complete, on_failure }
TaskDef Fields
FieldTypeDescription
idrequired string Unique task identifier within the flow
executorrequired string shell | http | noop | callback
config object Executor-specific config (see below)
input any Arbitrary JSON passed to the executor
depends_on string[] IDs of tasks that must complete first
timeout_secs integer Override queue default timeout
retries integer Override queue default retry count
backoff BackoffStrategy Override queue default backoff
Responses
201 Created 400 Invalid graph / missing executor 404 Queue not found
Request — Build/Test/Deploy Pipeline
POST /api/v1/queues/ci/flows

{
  "tasks": [
    {
      "id": "build",
      "executor": "shell",
      "config": { "command": "cargo build --release" }
    },
    {
      "id": "test",
      "executor": "shell",
      "config": { "command": "cargo test" },
      "depends_on": ["build"]
    },
    {
      "id": "deploy",
      "executor": "http",
      "config": {
        "url": "https://deploy.example.com/api",
        "method": "POST"
      },
      "depends_on": ["test"],
      "retries": 3
    }
  ]
}
Response — 201
{
  "id": "f_7k2m3n4p",
  "queue_id": "ci",
  "state": "running",
  "task_count": 3,
  "tasks_succeeded": 0,
  "tasks_failed": 0,
  "created_at": "2024-01-15T10:01:00Z",
  "updated_at": "2024-01-15T10:01:00Z"
}
GET /api/v1/queues/{qid}/flows List flows in a queue ▶
Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Responses
200 OK 404 Queue not found
Response — 200
[
  {
    "id": "f_7k2m3n4p",
    "queue_id": "ci",
    "state": "succeeded",
    "task_count": 3,
    "tasks_succeeded": 3,
    "tasks_failed": 0,
    "created_at": "2024-01-15T10:01:00Z",
    "updated_at": "2024-01-15T10:01:28Z"
  }
]
GET /api/v1/flows/{fid} Get flow detail with tasks ▶

Returns the flow and all its tasks with current state, output, and timing information.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
Responses
200 OK 404 Flow not found
Response — 200
{
  "id": "f_7k2m3n4p",
  "queue_id": "ci",
  "state": "running",
  "task_count": 2,
  "tasks_succeeded": 1,
  "tasks_failed": 0,
  "created_at": "2024-01-15T10:01:00Z",
  "updated_at": "2024-01-15T10:01:03Z",
  "tasks": [
    {
      "id": "build",
      "flow_id": "f_7k2m3n4p",
      "queue_id": "ci",
      "state": "succeeded",
      "executor_type": "shell",
      "input": null,
      "output": { "exit_code": 0, "stdout": "", "stderr": "" },
      "error": null,
      "retries_remaining": 3,
      "timeout_secs": 300,
      "started_at": "2024-01-15T10:01:01Z",
      "completed_at": "2024-01-15T10:01:02Z",
      "created_at": "2024-01-15T10:01:00Z"
    },
    {
      "id": "test",
      "flow_id": "f_7k2m3n4p",
      "queue_id": "ci",
      "state": "running",
      "executor_type": "shell",
      "input": null,
      "output": null,
      "error": null,
      "retries_remaining": 3,
      "timeout_secs": 300,
      "started_at": "2024-01-15T10:01:03Z",
      "completed_at": null,
      "created_at": "2024-01-15T10:01:00Z"
    }
  ]
}
DELETE /api/v1/flows/{fid} Cancel a flow ▶

Cancels a running flow and all its pending/running tasks. Already-completed tasks are unaffected.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
Responses
204 No Content 404 Flow not found
GET /api/v1/flows/{fid}/events Stream flow events (SSE) ▶

Server-Sent Events stream of task state changes and flow completion. Connect with any SSE client (EventSource in JavaScript, curl with streaming).

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
Event Types
EventDescriptionData Fields
task_state Emitted when a task changes state task_id, state, output, error, started_at, completed_at
task_output Emitted when a running task's output updates (streaming) task_id, output
flow_complete Emitted when flow reaches terminal state. Stream closes after this event. flow_id, state, task_count, tasks_succeeded, tasks_failed
Responses
200 Stream 404 Flow not found
curl
curl -N http://localhost:8080/api/v1/flows/f_7k2m/events
JavaScript
const es = new EventSource('/api/v1/flows/f_7k2m/events');
es.addEventListener('task_state', (e) => console.log(JSON.parse(e.data)));
es.addEventListener('flow_complete', (e) => {
  console.log(JSON.parse(e.data));
  es.close();
});

Tasks

The callback executor pauses a task in running state until an external system acknowledges it via this endpoint.

POST /api/v1/flows/{fid}/tasks/{tid}/ack Acknowledge a callback task ▶

Reports the outcome of a callback task. On failure, set retryable: true to allow the engine to retry.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
tidrequired string Task ID
Request Body
FieldTypeDescription
statusrequired string "success" or "failed"
output any JSON output (for success)
error string Error message (for failed)
retryable boolean Allow engine to retry. Default: false
Responses
204 No Content 400 Invalid status 404 Not found 409 Invalid state
Success acknowledgement
POST /api/v1/flows/f_7k2m/tasks/process/ack

{
  "status": "success",
  "output": { "records": 1042 }
}
Retryable failure
POST /api/v1/flows/f_7k2m/tasks/process/ack

{
  "status": "failed",
  "error": "Upstream returned 503",
  "retryable": true
}

Schedules

Schedules attach cron expressions to flow definitions, automatically submitting flows on a recurring basis.

POST /api/v1/queues/{qid}/schedules Create a schedule ▶

Creates a new cron schedule. The engine will submit the provided flow definition each time the cron expression fires.

Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Request Body
FieldTypeDescription
cronrequired string Cron expression (5-field standard or 7-field with seconds)
flowrequired FlowDef Flow definition to submit on each trigger
Responses
201 Created 400 Invalid cron expression 404 Queue not found
Request — Nightly backup at midnight
POST /api/v1/queues/ops/schedules

{
  "cron": "0 0 * * *",
  "flow": {
    "tasks": [
      {
        "id": "backup",
        "executor": "shell",
        "config": { "command": "./backup.sh" }
      }
    ]
  }
}
Response — 201
{
  "id": "s_9x4k7m",
  "queue_id": "ops",
  "cron": "0 0 * * *",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}
GET /api/v1/queues/{qid}/schedules List schedules for a queue ▶

Returns all schedules associated with a queue.

Path Parameters
ParamTypeDescription
qidrequired string Queue ID
Responses
200 OK 404 Queue not found
Response — 200
[
  {
    "id": "s_9x4k7m",
    "queue_id": "ops",
    "cron": "0 0 * * *",
    "last_fired_at": "2024-01-15T00:00:00Z",
    "created_at": "2024-01-14T10:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z"
  }
]
GET /api/v1/schedules/{sid} Get schedule detail ▶

Returns the full schedule including the embedded flow definition.

Path Parameters
ParamTypeDescription
sidrequired string Schedule ID
Responses
200 OK 404 Not found
Response — 200
{
  "id": "s_9x4k7m",
  "queue_id": "ops",
  "cron": "0 0 * * *",
  "flow": {
    "tasks": [
      {
        "id": "backup",
        "executor": "shell",
        "config": { "command": "./backup.sh" }
      }
    ]
  },
  "last_fired_at": "2024-01-15T00:00:00Z",
  "created_at": "2024-01-14T10:00:00Z",
  "updated_at": "2024-01-15T00:00:00Z"
}
PUT /api/v1/schedules/{sid} Update a schedule ▶

Replaces the cron expression and/or flow definition for an existing schedule.

Path Parameters
ParamTypeDescription
sidrequired string Schedule ID
Request Body
FieldTypeDescription
cronrequired string New cron expression
flowrequired FlowDef New flow definition
Responses
200 OK 400 Invalid cron expression 404 Not found
DELETE /api/v1/schedules/{sid} Delete a schedule ▶

Permanently deletes a schedule. Future cron triggers for this schedule will no longer fire.

Path Parameters
ParamTypeDescription
sidrequired string Schedule ID
Responses
204 No Content 404 Not found

Artifacts

Upload, download, and list shared files between tasks in a flow. Shell tasks access artifacts via the $TASKED_ARTIFACTS directory; container tasks use these HTTP endpoints via $TASKED_ARTIFACT_URL. Artifacts are cleaned up when the flow completes.

PUT /api/v1/flows/{fid}/artifacts/{name} Upload artifact ▶

Uploads a file as a named artifact for the flow. The request body is the raw file content. Overwrites any existing artifact with the same name.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
namerequired string Artifact name (filename)
Request Body

Raw file content (any content type).

Responses
201 Created 404 Flow not found
Example
curl -X PUT http://localhost:8080/api/v1/flows/f_7k2m3n4p/artifacts/myapp \
  --data-binary @target/release/myapp
GET /api/v1/flows/{fid}/artifacts/{name} Download artifact ▶

Downloads a named artifact from the flow. Returns the raw file content.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
namerequired string Artifact name (filename)
Responses
200 OK 404 Not found
Example
curl http://localhost:8080/api/v1/flows/f_7k2m3n4p/artifacts/myapp -o myapp
GET /api/v1/flows/{fid}/artifacts List artifacts ▶

Lists all artifacts stored for the flow.

Path Parameters
ParamTypeDescription
fidrequired string Flow ID
Responses
200 OK 404 Flow not found
Response
[
  {
    "name": "myapp",
    "size": 4523008,
    "created_at": "2024-01-15T10:05:00Z"
  },
  {
    "name": "report.csv",
    "size": 2048,
    "created_at": "2024-01-15T10:06:00Z"
  }
]

Schemas

Reference for shared types used across the API.

QueueConfig
Execution policy for a queue. All fields optional with defaults.
FieldTypeDefaultDescription
concurrency integer 10 Max concurrent running tasks
max_retries integer 3 Default retry count for tasks
timeout_secs integer 300 Default task timeout in seconds
backoff BackoffStrategy Exponential 1000ms Default retry backoff strategy
rate_limit RateLimitConfig? null Optional token-bucket rate limit
retention_secs integer? null Auto-delete terminal flows older than this (seconds)
BackoffStrategy
Tagged enum — exactly one variant per object.
// Fixed delay
{ "Fixed": { "delay_ms": 1000 } }

// Exponential (doubles each retry)
{ "Exponential": { "initial_delay_ms": 1000 } }

// Exponential with jitter
{ "ExponentialJitter": { "initial_delay_ms": 1000 } }
RateLimitConfig
Token-bucket rate limiter applied to task dispatch.
FieldTypeDescription
max_burstrequired integer Bucket capacity (burst size)
per_secondrequired number Sustained token refill rate
FlowWebhooks
Optional webhook URLs for flow lifecycle notifications. Both fields are optional.
FieldTypeDescription
on_complete string? URL to POST when the flow succeeds
on_failure string? URL to POST when the flow fails
FlowState
Lifecycle state of a flow.
running succeeded failed cancelled
TaskState
Lifecycle state of a task.
pending ready running succeeded failed delayed cancelled
Executor Configs
The config field on TaskDef varies by executor type.
ExecutorConfig Fields
shell command (string) — shell command to execute. Returns { exit_code, stdout, stderr }
http url, method, headers (object), body (string). Returns { status, body }
noop No config. Completes immediately.
callback No config. Waits for POST ack call.

Errors

All errors return a JSON object with machine-readable error code and human-readable message.

Error Response Format
{
  "error": "queue_not_found",
  "message": "Queue 'my-queue' not found"
}
Error Codes
CodeHTTPDescription
queue_not_found 404 Queue does not exist
queue_already_exists 409 Queue ID is already taken
flow_not_found 404 Flow does not exist
task_not_found 404 Task does not exist in the specified flow
no_executor 400 Unknown executor type
invalid_graph 400 DAG validation failed (cycles, missing deps)
invalid_status 400 Ack status must be "success" or "failed"
invalid_state_transition 409 Task/flow not in a valid state for the operation
schedule_not_found 404 Schedule does not exist
invalid_cron 400 Cron expression could not be parsed
internal_error 500 Unexpected server error