# SimpleQ

> SimpleQ is the managed job queue for AI and API-heavy backends — a managed transport layer that delivers your jobs to an HTTP endpoint you control. Publish over REST or the TypeScript SDK; SimpleQ handles retries, per-queue rate limiting, backpressure (429/503/529 defer without burning a retry), a dead-letter queue, and ack mode for long-running work. You run the business logic; SimpleQ handles delivery — no polling workers, no broker, no framework to adopt. Your worker is a plain HTTP endpoint: verify the signature, do the work, return 200.

SimpleQ is a managed transport for async workloads — comparable to AWS SQS, Google Cloud Tasks, or Upstash QStash, but batteries-included: push delivery to webhooks, configurable retries with exponential or fixed backoff, per-queue rate limiting, dead-letter queues with replay, ack mode for long-running work, and a real-time dashboard. It is purpose-built for AI-heavy backends, API-dependent SaaS, and any async processing that needs reliability without infrastructure overhead.

## What SimpleQ does

- REST API to publish jobs: `POST /v1/queues/:queueName/jobs`
- Webhook-based delivery: POSTs job payloads to your endpoint with HMAC signing (`x-simpleq-signature`)
- Configurable retries with exponential or fixed backoff per queue
- Dead-letter queues with single and bulk replay
- Per-queue rate limiting (fixed-window)
- Ack mode for long-running work: webhook confirms receipt, your app calls `/ack` when done
- Nack: fail-fast signal for ack-mode jobs (`POST /v1/jobs/:id/nack`)
- Defer: backpressure signal that holds and redelivers without burning a retry (`POST /v1/jobs/:id/defer`)
- 429/503/529 webhook backpressure handling — waits and retries without counting against maxAttempts
- Idempotency keys to prevent duplicate jobs
- Delayed jobs (delay in seconds, max 86400 = 24h)
- Queue templates for common workloads (e.g., `template: "anthropic"` or `template: "openai"` for AI API defaults)
- Per-job attempt history and status tracking (pending → processing → awaiting_ack → completed | dead)
- Dashboard with real-time queue stats, per-job logs, and DLQ management
- All customer-facing durations are in seconds

## Who it's for

SimpleQ is built for seed-stage through growth-stage engineering teams — especially those building with AI. If your backend makes LLM API calls (OpenAI, Anthropic, Google), delivers webhooks to customers, syncs data to third-party APIs, or runs any async work that needs retries and rate limiting — SimpleQ replaces the queue infrastructure you'd otherwise build and maintain yourself.

## Auth

- Dashboard login: WorkOS (B2B SSO, SCIM, Organizations) at https://app.simpleq.io
- API auth: `Authorization: Bearer sq_live_...` — keys are created and revoked from the dashboard

## Quickstart

```bash
# 1. Create a queue (from the dashboard or API)
curl -X POST https://api.simpleq.io/v1/queues \
  -H "Authorization: Bearer sq_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ai-jobs",
    "webhookUrl": "https://your-app.com/webhook",
    "maxAttempts": 5,
    "backoffType": "exponential",
    "backoffDelay": 2,
    "rateLimitMax": 50,
    "rateLimitWindow": 60
  }'

# 2. Publish a job
curl -X POST https://api.simpleq.io/v1/queues/ai-jobs/jobs \
  -H "Authorization: Bearer sq_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "model": "claude-sonnet-4-20250514",
      "messages": [{ "role": "user", "content": "Summarize this document" }]
    },
    "idempotencyKey": "summary_req_456",
    "delay": 5
  }'

# 3. SimpleQ POSTs the job to your webhook when ready — your payload inside a JSON
#    envelope: { id, queue, payload, attempt, maxAttempts, createdAt }. Read body.payload.
# Your webhook verifies the x-simpleq-signature header, then handles the business logic.
```

## API surface

Queue management:
- `POST /v1/queues` — create a queue
- `GET /v1/queues` — list queues
- `GET /v1/queues/:id` — get queue detail
- `PUT /v1/queues/:id` — update queue config
- `DELETE /v1/queues/:id` — soft-delete queue

Job operations:
- `POST /v1/queues/:queueName/jobs` — publish a job (body: `{ payload, idempotencyKey?, delay? }`)
- `GET /v1/queues/:id/jobs` — list jobs in a queue (paginated, filterable by status)
- `GET /v1/jobs/:id` — get job status and history
- `POST /v1/jobs/:id/ack` — acknowledge completion (ack-mode queues)
- `POST /v1/jobs/:id/nack` — signal failure (ack-mode; `{ retryable?: bool, reason?: string }`)
- `POST /v1/jobs/:id/defer` — backpressure hold (ack-mode; `{ retryAfter: seconds, reason?: string }`)

Dead-letter queue:
- `GET /v1/queues/:id/dlq` — list dead-letter jobs
- `POST /v1/queues/:id/dlq/:jobId/replay` — replay one DLQ job as a fresh job
- `POST /v1/queues/:id/dlq/replay` — bulk replay (`{ jobIds: [...] }` or `{ all: true }`, max 1000)

## Job delivery (what your endpoint receives)

When a job is ready, SimpleQ `POST`s it to your queue's `webhookUrl`. Headers: `Content-Type: application/json` and `x-simpleq-signature: sha256=<hex>` (HMAC-SHA256 of the raw body — verify it). The body is an envelope, not the raw payload:

```json
{ "id": "job_abc123", "queue": "ai-jobs", "payload": { /* your data, verbatim */ }, "attempt": 1, "maxAttempts": 5, "createdAt": "2025-01-15T10:30:00.000Z" }
```

Read your data from `body.payload`. Return `2xx` to confirm receipt (15s timeout in standard mode); non-2xx or timeout is retried with backoff, then dead-lettered. Full contract: https://docs.simpleq.io/concepts/job-delivery

## Machine-readable API spec

- [OpenAPI 0.0.1 spec (JSON)](https://docs.simpleq.io/openapi.json) — machine-readable definition; import to generate a client
- [API reference](https://docs.simpleq.io/reference/) — human-readable reference: every endpoint, request body, and status code
- [Interactive API explorer](https://docs.simpleq.io/reference/explorer) — try requests in your browser

## SDKs

- **TypeScript (official):** [`@simpleq/sdk` — the official Node/TypeScript SDK for SimpleQ](https://docs.simpleq.io/sdk/) — `npm install @simpleq/sdk`. Publish with automatic idempotent retries, webhook signature verification (`verifyWebhook`), ack/nack/defer callbacks, and Express + Nest.js adapters. Node 22+, ESM + CJS, zero runtime dependencies. ([GitHub](https://github.com/simpleqio/simpleq-sdk-typescript) · [npm](https://www.npmjs.com/package/@simpleq/sdk))
- **Other languages:** the API is HTTP-first — any language that can make an HTTP request works today (complete reference workers in Python, Go, Java, PHP, and C#/.NET are in the examples). More official SDKs are coming.

## What SimpleQ does NOT do

- Not a workflow engine — no durable execution, no step functions, no signals/timers (compare: Temporal, Inngest)
- No built-in connectors or integrations — it delivers to any HTTP endpoint you control
- No cron/scheduled recurring jobs (yet)

## Queue templates

Queue templates prefill sensible defaults for common workloads. Currently available:
- `"anthropic"` — ack mode, 600s timeout, exponential backoff tuned for Anthropic's API (handles 429/529 backpressure)
- `"openai"` — ack mode, 300s timeout, exponential backoff tuned for OpenAI's API (handles 429 rate limiting)

Pass the template name when creating a queue. Explicit fields override template values.

## Comparable tools

- Managed queue services: AWS SQS, Google Cloud Tasks, Upstash QStash
- Self-hosted queue libraries: BullMQ + Redis, Sidekiq, Celery
- Self-hosted brokers & streaming: RabbitMQ, Apache Kafka
- Webhook delivery platforms: Svix, Hookdeck

SimpleQ competes with managed queue services and self-hosted queue setups — not with workflow engines like Temporal, Inngest, or Trigger.dev.

## Concepts

- [Concept: Ack mode](https://docs.simpleq.io/concepts/ack-mode) — acknowledge receipt immediately, run the work out of band, report back with ack / nack / defer
- [Concept: Backpressure](https://docs.simpleq.io/concepts/backpressure) — relay a downstream 429 / 503 / 529 to defer a job without burning an attempt
- [Concept: Comparison](https://docs.simpleq.io/concepts/comparison/) — technical comparison table + per-tool breakdowns — QStash, SQS, Cloud Tasks, BullMQ, Inngest, Trigger.dev, Kafka, RabbitMQ
- [Concept: Editing a queue](https://docs.simpleq.io/concepts/editing-a-queue) — change any queue setting except its name, and when each change takes effect
- [Concept: Idempotency](https://docs.simpleq.io/concepts/idempotency) — dedupe publishes with idempotencyKey; dedupe redeliveries in your worker
- [Concept: Job delivery to your webhook](https://docs.simpleq.io/concepts/job-delivery) — the exact request your webhook receives — headers and the JSON envelope schema
- [Concept: Local development](https://docs.simpleq.io/concepts/local-development) — expose a localhost worker through a Cloudflare tunnel and point your queue webhookUrl at it
- [Concept: Signature verification](https://docs.simpleq.io/concepts/signature-verification) — verify the x-simpleq-signature HMAC-SHA256 header on every webhook

## Integration examples

Copy-paste integration examples with reference workers in Node, Python, Go, Java, PHP, C#/.NET, Express, Nest.js, and FastAPI:
- [Example: Anthropic queue](https://docs.simpleq.io/examples/anthropic-queue/) — A queue pre-configured for Anthropic API workloads, plus a reference worker.
- [Example: Generic ack worker](https://docs.simpleq.io/examples/generic-ack-worker/) — A minimal worker that implements the SimpleQ ack-mode protocol with no downstream provider SDK — just SimpleQ's own `@simpleq/sdk` in Node, plain HTTP everywhere else.
- [Example: OpenAI queue](https://docs.simpleq.io/examples/openai-queue/) — A queue pre-configured for OpenAI API workloads, plus a reference worker.
- [Example: Standard mode queue](https://docs.simpleq.io/examples/standard-mode-queue/) — A standard-mode queue delivers each job to your webhook; your handler does the work and returns `2xx` to mark the job done.

## Product pages

- [Home](https://simpleq.io/) — product overview, features, use cases, dashboard preview
- [Pricing](https://simpleq.io/pricing) — free tier (30,000 attempts/mo, 5 queues, all features), then usage-based from $19/mo (preview pricing); billed per outbound delivery attempt (every webhook POST, including ones answered 429/503/529); defer holds, publishes, and ack/nack calls are free, and backpressure never burns the retry budget
- [Use Cases](https://simpleq.io/use-cases) — AI job processing, AI agent pipelines, bulk API sync, backpressure handling, delayed jobs, ack mode
- [Serverless background jobs](https://simpleq.io/serverless-background-jobs) — run background jobs on Vercel/Next.js, AWS Lambda, Cloudflare Workers, and Supabase with no always-on worker process; per-platform quickstarts
- [Compare](https://simpleq.io/compare) — feature-by-feature comparisons with QStash, SQS, Cloud Tasks, BullMQ, Inngest, Trigger.dev, Kafka, RabbitMQ
- [SimpleQ vs Upstash QStash](https://simpleq.io/compare/vs-qstash) — closest match: HTTP publish + HTTP push delivery; backpressure that never burns a retry, three-signal ack protocol (ack/nack/defer)
- [SimpleQ vs AWS SQS](https://simpleq.io/compare/vs-sqs) — push vs pull, rate limiting, ack mode, DLQ replay
- [SimpleQ vs Google Cloud Tasks](https://simpleq.io/compare/vs-cloud-tasks) — ack mode, DLQ replay, backpressure
- [SimpleQ vs BullMQ](https://simpleq.io/compare/vs-bullmq) — managed vs self-hosted, HTTP push delivery vs in-process workers
- [SimpleQ vs Inngest](https://simpleq.io/compare/vs-inngest) — transport vs workflow engine
- [SimpleQ vs Trigger.dev](https://simpleq.io/compare/vs-trigger-dev) — transport vs managed execution
- [SimpleQ vs Apache Kafka](https://simpleq.io/compare/vs-kafka) — HTTP push vs streaming log, backpressure that never burns retries, DLQ replay, AI templates
- [SimpleQ vs RabbitMQ](https://simpleq.io/compare/vs-rabbitmq) — managed push vs self-hosted broker, backpressure that never burns retries, DLQ replay, per-queue HMAC signing
- [Docs](https://docs.simpleq.io/) — full documentation, API reference, examples
- [Contact](https://simpleq.io/contact) — design partner inquiries, enterprise, general contact

## Blog posts

- [Why every AI app needs a reliable job queue](https://simpleq.io/blog/why-every-ai-app-needs-a-reliable-job-queue) — why inline LLM calls are the biggest hidden reliability risk, and how a managed queue fixes it
- [Queue vs workflow engine: what startups actually need](https://simpleq.io/blog/queue-vs-workflow-engine-what-startups-actually-need) — pragmatic comparison of queues vs Temporal/Inngest with decision matrix
- [How to handle OpenAI rate limits in production](https://simpleq.io/blog/how-to-handle-openai-rate-limits-in-production) — TPM/RPM mechanics, per-queue rate limiting, backoff strategies
- [Why job retries matter](https://simpleq.io/blog/why-job-retries-matter) — the four reliability primitives for background jobs: idempotency, exponential backoff with jitter, dead-letter queues, and signed delivery
- [Building async infrastructure without overengineering](https://simpleq.io/blog/building-async-infrastructure-without-overengineering) — staged progression from inline calls to managed queues
- [What is a managed job queue?](https://simpleq.io/blog/what-is-a-managed-job-queue) — what a managed job queue is, push vs pull vs self-hosted, and when you need one
- [Idempotency keys: making job publishing safe to retry](https://simpleq.io/blog/idempotency-keys-for-jobs) — publish-boundary dedup, and at-least-once delivery vs exactly-once effects
- [Dead-letter queues: catching and replaying failed jobs](https://simpleq.io/blog/dead-letter-queues-explained) — what to capture per attempt, and the inspect-fix-replay loop (single + bulk)
- [Rate limiting strategies for API-dependent backends](https://simpleq.io/blog/rate-limiting-strategies-for-apis) — fixed-window vs token-bucket vs sliding-window, shared budgets, Retry-After across a fleet
- [Backpressure: handling 429, 503, and 529 without losing work](https://simpleq.io/blog/backpressure-429-503-529) — failure vs backpressure; defer on Retry-After without burning attempts
- [Running jobs longer than a webhook timeout: ack mode](https://simpleq.io/blog/ack-mode-long-running-jobs) — the 15s ceiling, and reporting outcomes via ack / nack / defer
- [How to verify webhook signatures (HMAC-SHA256)](https://simpleq.io/blog/verify-webhook-signatures-hmac) — x-simpleq-signature over the raw body, constant-time compare, per-queue secrets

## Full documentation

For the complete text of every concept page, example, and API endpoint, see [llms-full.txt](https://docs.simpleq.io/llms-full.txt).

## Contact

- Email: support@simpleq.io
- Enterprise / sales: support@simpleq.io
- LinkedIn: https://www.linkedin.com/company/simpleq-io