Background Jobs

Enqueue a handler with one HTTP call, no sequence required. It is the Orch8 equivalent of a BullMQ, Sidekiq, or Celery job, backed by the same durable engine: retries with backoff, delayed runs, idempotency keys, and a dead-letter queue.

1curl -X POST http://localhost:8080/api/v1/jobs \
2  -H 'Content-Type: application/json' \
3  -H 'X-Tenant-Id: acme' \
4  -d '{
5        "handler": "send_email",
6        "payload": {"to": "ada@example.com", "template": "welcome"},
7        "retry": {"max_attempts": 5, "initial_backoff_ms": 1000},
8        "idempotency_key": "welcome-ada"
9      }'

How it works

A job is an ordinary workflow instance of a managed, single-step system sequence named _job.<handler>. The job id is the instance id, so workers (pull or push), retries, the DLQ, tenant isolation, and dashboard views all apply unchanged. The payload reaches your worker as task.params.

Request fields

handler (required), payload, queue, priority (low, normal, high, critical), retry (max_attempts counts total runs including the first, initial_backoff_ms, max_backoff_ms), delay_ms or run_at, idempotency_key, and metadata. A repeated idempotency key returns the existing job with 200.

Inspect, list, cancel

1GET    /api/v1/jobs/{id}        # status, attempts, output, error
2GET    /api/v1/jobs?handler=send_email&status=dead_lettered&limit=50&cursor=…
3DELETE /api/v1/jobs/{id}        # 200 cancelled, 202 cancel signalled, 409 already finished

Statuses are scheduled, running, completed, failed (no retry policy), dead_lettered (retries exhausted), and cancelled. Lists are newest first with keyset pagination: {"items": [...], "next_cursor": "...", "has_more": true}.

From the Node SDK

1const job = await client.jobs.enqueue(
2  "send_email",
3  { to: "ada@example.com", template: "welcome" },
4  { retry: { max_attempts: 5, initial_backoff_ms: 1_000 }, idempotencyKey: "welcome-ada" },
5);
6const done = await client.jobs.waitFor(job.id, { timeoutMs: 120_000 });

From the CLI

1orch8 job enqueue send_email --payload '{"to":"ada@example.com"}' --max-attempts 5
2orch8 job list --handler send_email --status dead_lettered
3orch8 job cancel <id> --yes

The Python, Go, Java, .NET, Ruby, and PHP SDKs expose the same calls. Full reference: docs/JOBS.md in the engine repository.