Queue Endpoints

Background job queue management powered by BullMQ, Redis, or in-memory queues.

Configuration

BullMQ (Recommended)

{
  "queue": {
    "name": "default",
    "type": "bullmq",
    "concurrency": 5,
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "{{env.REDIS_PASSWORD}}"
    },
    "defaultJobOptions": {
      "maxAttempts": 3,
      "backoff": { "type": "exponential", "delay": 1000 }
    }
  }
}

Redis

{
  "queue": {
    "name": "default",
    "type": "redis",
    "concurrency": 5,
    "redis": {
      "url": "{{env.REDIS_URL}}"
    }
  }
}

Memory (Dev)

{
  "queue": {
    "name": "default",
    "type": "memory",
    "concurrency": 1
  }
}

Get Queue Stats

GET /queue/stats

Get queue statistics.

curl http://localhost:3000/queue/stats \
  -H "Authorization: Bearer <token>"

Response:

{
  "waiting": 10,
  "active": 2,
  "completed": 5000,
  "failed": 15,
  "delayed": 5,
  "paused": 0,
  "total": 5032
}

Add Job

POST /queue/jobs

Add job to queue.

curl -X POST http://localhost:3000/queue/jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "send-email",
    "data": {
      "to": "user@example.com",
      "subject": "Hello"
    },
    "options": {
      "priority": 1,
      "delay": 60000
    }
  }'

Response:

{
  "id": "job-123",
  "name": "send-email",
  "status": "waiting"
}

Get Job

GET /queue/jobs/:id

Get job details.

curl http://localhost:3000/queue/jobs/job-123 \
  -H "Authorization: Bearer <token>"

Response:

{
  "id": "job-123",
  "name": "send-email",
  "status": "completed",
  "data": {...},
  "result": {...},
  "progress": 100,
  "attempts": 1,
  "createdAt": "2024-01-01T00:00:00Z",
  "completedAt": "2024-01-01T00:00:05Z"
}

List Jobs

GET /queue/jobs

List jobs by status.

curl "http://localhost:3000/queue/jobs?status=failed&limit=10" \
  -H "Authorization: Bearer <token>"

Response:

{
  "jobs": [
    {
      "id": "job-456",
      "name": "send-email",
      "status": "failed",
      "error": "SMTP connection failed"
    }
  ]
}

Retry Job

POST /queue/jobs/:id/retry

Retry failed job.

curl -X POST http://localhost:3000/queue/jobs/job-456/retry \
  -H "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "status": "waiting"
}

Remove Job

DELETE /queue/jobs/:id

Remove job.

curl -X DELETE http://localhost:3000/queue/jobs/job-456 \
  -H "Authorization: Bearer <token>"

Clean Queue

POST /queue/clean

Clean old jobs.

curl -X POST http://localhost:3000/queue/clean \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "olderThan": 86400000
  }'

Response:

{
  "cleaned": 500
}

Pause/Resume

POST /queue/pause

Pause queue processing.

curl -X POST http://localhost:3000/queue/pause \
  -H "Authorization: Bearer <token>"

POST /queue/resume

Resume queue processing.

curl -X POST http://localhost:3000/queue/resume \
  -H "Authorization: Bearer <token>"

Job Options

Option	Type	Description
priority	number	1-20 (lower = higher priority)
delay	number	Delay in milliseconds
attempts	number	Max retry attempts
backoff	object	Retry backoff config
timeout	number	Job timeout in ms (default: 30000)

{
  "options": {
    "priority": 1,
    "delay": 60000,
    "attempts": 3,
    "backoff": {
      "type": "exponential",
      "delay": 1000
    },
    "timeout": 30000
  }
}

Priority Levels

Level	Value	Use Case
LOW	1	Background tasks
NORMAL	5	Default priority
HIGH	10	Important tasks
CRITICAL	20	Urgent processing

Recurring Jobs (BullMQ)

Schedule recurring jobs with cron patterns or intervals.

Cron Pattern

curl -X POST http://localhost:3000/queue/jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-report",
    "data": { "type": "summary" },
    "options": {
      "repeat": {
        "pattern": "0 9 * * *"
      }
    }
  }'

Fixed Interval

curl -X POST http://localhost:3000/queue/jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sync-data",
    "data": { "source": "external-api" },
    "options": {
      "repeat": {
        "every": 300000,
        "limit": 100
      }
    }
  }'

Repeat Options

Option	Type	Description
pattern	string	Cron expression (e.g., 0 0 * * *)
every	number	Interval in milliseconds
limit	number	Max repetitions
immediately	boolean	Run immediately on creation

Job Callbacks

Trigger actions on job events.

{
  "name": "process-order",
  "data": { "orderId": "123" },
  "callbacks": {
    "onComplete": [
      {
        "type": "http",
        "url": "https://api.example.com/webhook",
        "method": "POST",
        "body": { "status": "completed" }
      }
    ],
    "onFailed": [
      {
        "type": "slack",
        "channel": "#alerts",
        "text": "Order processing failed"
      }
    ]
  }
}

Queue Metrics

GET /queue/metrics

Get detailed queue metrics (BullMQ only).

{
  "jobsProcessed": 1500,
  "jobsCompleted": 1480,
  "jobsFailed": 20,
  "jobsRetried": 15,
  "avgProcessingTime": 245,
  "jobsPerSecond": 12.5,
  "errorRate": 0.013
}

Integration with Routes

Queue jobs from route handlers:

{
  "path": "/orders",
  "method": "POST",
  "supabaseQueries": [{
    "table": "orders",
    "operation": "insert",
    "data": { "status": "pending" }
  }],
  "integrations": {
    "actions": [
      {
        "type": "queue",
        "queue": "default",
        "jobName": "process-order",
        "data": { "orderId": "{{supabase.0.id}}" },
        "options": { "priority": 10 }
      }
    ]
  }
}