my-queue-api

---
name: my-queue-api
version: 1.0.0
description: >
  Durable job queue — enqueue work and have it retried against your HTTP consumer, with concurrency caps and a dependency DAG.
triggers: [queue, job queue, background job, enqueue, retry, async work, dead letter, delayed job, concurrency]
checksum: sha256-pending
---

# MyQueueAPI

A queue is a named, durable pipeline of jobs. Each queue has an HTTP `consumer_url`; every job is POSTed there, and a 2xx response succeeds the job. Failed jobs retry with backoff up to `max_attempts`, then dead-letter.

## Capabilities
<!-- llm:start -->
`queue` is the **durable async machine work** layer. Use it when work must run reliably, eventually — not inline with the request that triggered it.

A queue is created with:

| Field | Meaning |
|---|---|
| `consumer_url` | HTTP(S) endpoint each job payload is POSTed to. A 2xx succeeds the job. |
| `max_attempts` | Retries before a job dead-letters (default 5). |
| `max_concurrency` | Max jobs dispatched at once (default 5). |

A job carries an arbitrary JSON `payload` (≤256 KB). Jobs support:

- `dedup_key` — idempotency: a repeated key returns the existing job.
- `delay_seconds` — hold the job before it becomes eligible.
- `depends_on` — job ids this job waits on. Immutable — a DAG by construction. A job with unsucceeded `depends_on` starts blocked.

**queue vs workflow vs task** — see `docs/orchestration-decision-guide.md`. Short version: `workflow` reacts to inbound webhooks inline; `queue` runs durable retried machine work; `task` is for work that needs an agent/human decision.
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi queue create <name> --consumer-url <url> [--max-attempts <n>] [--max-concurrency <n>]` | Create a queue |
| `myapi queue list` | List queues in your org |
| `myapi queue get <name>` | Show a queue's retry/concurrency policy |
| `myapi queue enqueue <name> --payload <json> [--dedup-key <k>] [--delay <s>] [--depends-on <id,id>]` | Enqueue a job |
| `myapi queue jobs <name> [--status <s>] [--limit <n>]` | List a queue's jobs |
| `myapi queue job <job_id>` | Show a single job's status |
<!-- generated:end -->

## Examples
<!-- llm:start -->
```bash
# 1. Create a queue whose jobs POST to your handler
myapi queue create thumbnails \
  --consumer-url https://fn.myapi.com/<org>/<fn_id> \
  --max-attempts 5 --max-concurrency 10

# 2. Enqueue work — idempotent on --dedup-key
myapi queue enqueue thumbnails \
  --payload '{"asset_id":"a_123","size":256}' \
  --dedup-key a_123-256

# 3. A job that waits on others (DAG)
J1=$(myapi queue enqueue build --payload '{"step":1}' --json | jq -r .id)
myapi queue enqueue build --payload '{"step":2}' --depends-on $J1

# 4. Inspect
myapi queue jobs thumbnails --status dead
myapi queue job <job_id>
```
<!-- llm:end -->

## Notes

- A 2xx from the `consumer_url` succeeds the job; anything else counts as a failed attempt.
- After `max_attempts` a job goes to `status: dead` (the dead-letter state) — it is not retried further.
- Job status values: `pending`, `blocked`, `running`, `succeeded`, `dead`.
- `depends_on` is immutable: the DAG is declared at enqueue time.
- `payload` is capped at 256 KB.

Run `myapi queue --help` for the full flag reference.