# SimpleQ

> SimpleQ is a managed job queue service — Queues as a Service. You publish jobs via REST API; SimpleQ queues them, retries failures, respects rate limits, and delivers each job to your webhook endpoint. You handle the business logic.

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, webhook delivery, 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 | failed | 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/retry` — retry a failed job
- `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/retry` — retry one DLQ job
- `POST /v1/queues/:id/dlq/retry` — bulk retry (`{ jobIds: [...] }` or `{ all: true }`, max 1000)

## Webhook 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/webhook-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

SDKs for TypeScript, Python, Go, Java, PHP, and C#/.NET are coming soon. Today the API is HTTP-first — any language that can make an HTTP request works.

## 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
- 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 — SQS, Cloud Tasks, BullMQ, Inngest, Trigger.dev, Kafka, RabbitMQ
- [Concept: Idempotency](https://docs.simpleq.io/concepts/idempotency) — dedupe publishes with idempotencyKey; dedupe redeliveries in your worker
- [Concept: Signature verification](https://docs.simpleq.io/concepts/signature-verification) — verify the x-simpleq-signature HMAC-SHA256 header on every webhook
- [Concept: Webhook delivery](https://docs.simpleq.io/concepts/webhook-delivery) — the exact request your webhook receives — headers and the JSON envelope schema

## Integration examples

Copy-paste integration examples with reference workers in Node, Python, Go, Java, PHP, C#/.NET, Express, Next.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 plain HTTP and no provider SDK.
- [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 during early access, all features included
- [Use Cases](https://simpleq.io/use-cases) — AI job processing, webhook delivery, bulk API sync, delayed jobs, SMS/email, ack mode
- [Compare](https://simpleq.io/compare) — feature-by-feature comparisons with SQS, Cloud Tasks, BullMQ, Inngest, Trigger.dev, Kafka, RabbitMQ
- [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, webhook 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) — push-to-webhook 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 webhook retries matter](https://simpleq.io/blog/why-webhook-retries-matter) — idempotency, backoff, dead-letter queues, and HMAC signing
- [Building async infrastructure without overengineering](https://simpleq.io/blog/building-async-infrastructure-without-overengineering) — staged progression from inline calls to managed queues

## Full documentation

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

## Contact

- Email: support@simpleq.io
- Enterprise / sales: support@simpleq.io