Docs · v1

SimpleQ documentation

The execution layer for AI jobs, webhooks, and API tasks. Get from zero to your first reliable background job in under five minutes.

Quickstart

You'll install the SDK, authenticate with an API key, and enqueue your first job. Each step takes about a minute.

1. Install SDK

terminal

bash

npm install @simpleq/sdk

2. Initialize client

lib/simpleq.ts

1import { SimpleQ } from "@simpleq/sdk";
2 
3const simpleq = new SimpleQ({
4  apiKey: process.env.SIMPLEQ_API_KEY
5});

3. Enqueue a job

server/welcome.ts

1await simpleq.enqueue({
2  queue: "default",
3  type: "webhook",
4  payload: {
5    url: "https://example.com/webhook",
6    method: "POST",
7    body: { event: "user.created" }
8  }
9});

That's it — your job is queued. Open the dashboard to see it move from queued → running → completed.

Install SDK

SDKs are available for TypeScript / JavaScript, Python, and Go. They all share the same primitives and the same API surface.

terminal

bash

# TypeScript / JavaScript
npm install @simpleq/sdk
 
# Python
pip install simpleq
 
# Go
go get github.com/simpleq/simpleq-go

Authentication

Generate an API key in the dashboard and pass it to the SDK as SIMPLEQ_API_KEY. Keys can be scoped to a single project and rotated at any time.

lib/simpleq.ts

1const simpleq = new SimpleQ({
2  apiKey: process.env.SIMPLEQ_API_KEY,
3  project: "production"
4});

Create a queue

Queues are logical groupings of jobs. Create one per workload — ai-jobs, webhooks, outbound-sms — so you can scale and rate-limit them independently.

setup/queues.ts

1await simpleq.queues.create({
2  name: "ai-jobs",
3  concurrency: 32,
4  retry: { maxAttempts: 5, backoff: "exponential" }
5});

Enqueue a job

Every job has a queue, a type, and a payload. Optionally attach an idempotency key, retry policy, and rate-limit key.

server/enqueue.ts

1await simpleq.enqueue({
2  queue: "ai-jobs",
3  type: "openai.chat",
4  idempotencyKey: `summary_${requestId}`,
5  payload: {
6    model: "gpt-4o-mini",
7    messages: [{ role: "user", content: text }]
8  },
9  retry: { maxAttempts: 5, backoff: "exponential" },
10  rateLimitKey: "openai-prod"
11});

Schedule a job

Schedule a one-off job at a specific time, or a recurring job with a cron expression and timezone. SimpleQ guarantees the job runs even across deploys.

schedules/index.ts

1// one-off
2await simpleq.schedule({
3  queue: "reminders",
4  type: "email.send-followup",
5  payload: { userId: "u_123" },
6  runAt: new Date(Date.now() + 1000 * 60 * 60 * 24)
7});
8 
9// recurring
10await simpleq.schedule({
11  queue: "digests",
12  type: "email.daily-digest",
13  cron: "0 9 * * 1-5",
14  timezone: "America/Los_Angeles"
15});

Retry policies

Configure max attempts, backoff strategy, and jitter per queue or per job. SimpleQ tracks every attempt and surfaces the full attempt history in the dashboard.

retry.json

json

1{
2  retry: {
3    maxAttempts: 5,
4    backoff: "exponential",   // "fixed" | "exponential"
5    initialDelayMs: 1000,
6    maxDelayMs: 60_000,
7    jitter: "full"            // "none" | "equal" | "full"
8  }
9}

When max attempts are exhausted, jobs land in the dead-letter queue for the queue they came from. Replay them from the dashboard or via the API.

Rate limits

Pass a rateLimitKey on enqueue to share a token bucket across all jobs that hit the same upstream. Configure the bucket once per key.

rate-limits.ts

1await simpleq.rateLimits.set("openai-prod", {
2  requestsPerSecond: 50,
3  burst: 100
4});

Webhooks

SimpleQ ships a http.request job type that handles retries, signing, and timeouts for outbound webhooks.

webhooks/deliver.ts

1await simpleq.enqueue({
2  queue: "webhooks",
3  type: "http.request",
4  idempotencyKey: `evt_${event.id}`,
5  payload: {
6    url: customer.webhookUrl,
7    method: "POST",
8    body: event,
9    headers: { "X-Signature": sign(event) },
10    timeoutMs: 30_000
11  },
12  retry: { maxAttempts: 8, backoff: "exponential" }
13});

OpenAI connector

The OpenAI connector handles auth, retries on 429s and 5xxs, and rate-limit pacing across your workers.

ai/chat.ts

1await simpleq.enqueue({
2  queue: "ai-jobs",
3  type: "openai.chat",
4  payload: {
5    model: "gpt-4o-mini",
6    messages: [{ role: "user", content: "Hello, world" }]
7  },
8  rateLimitKey: "openai-prod"
9});

API reference

The full REST API mirrors the SDK. Authenticate with Authorization: Bearer $SIMPLEQ_API_KEY.

api

http

POST   /v1/jobs                  Enqueue a job
POST   /v1/jobs/:id/retry        Retry a failed job
GET    /v1/jobs/:id              Get job status
POST   /v1/schedules             Create a schedule
GET    /v1/queues                List queues
POST   /v1/rate-limits/:key      Set rate limit