api reference · http
The HTTP API, every endpoint.
The bunqueue HTTP API runs on port 6790 by default, configurable via the HTTP_PORT environment variable. All request and response bodies use JSON (Content-Type: application/json) unless otherwise noted.
**Response contract:** Unless an endpoint explicitly documents another media type or shape, JSON command responses include an `ok` boolean. Successful responses return `"ok": true` with operation-specific data; failures return `"ok": false` with an `"error"` string. `GET /queues/summary` is the intentional JSON exception: it returns the summary array directly. Health probe text, Prometheus output, SSE, and WebSocket frames use their documented formats.
```json
// Success
{ "ok": true, "id": "019ce9d7-6983-7000-946f-48737be2b0f9" }
// Error
{ "ok": false, "error": "Job not found" }
```
---
## Authentication
When `AUTH_TOKENS` is configured, protected endpoints require a Bearer token in
the `Authorization` header. Health probes and CORS preflight stay public;
`/prometheus` is also public unless metrics authentication is enabled. Multiple
tokens are supported, separated by commas.
```bash
# Server configuration (env var)
AUTH_TOKENS=secret-token-1,secret-token-2
# Or in bunqueue.config.ts:
# auth: { tokens: ['secret-token-1', 'secret-token-2'] }
# Client usage
curl -H "Authorization: Bearer secret-token-1" http://localhost:6790/stats
```
Token comparison uses **constant-time equality** (`crypto.timingSafeEqual` equivalent) to prevent timing attacks. Each token is compared against all configured tokens, ensuring no information leaks about token length or prefix.
**Endpoints that skip authentication:**
| Endpoint | Reason |
| --------------------------- | ------------------------------------------------------------- |
| `GET /health` | Load balancer health checks must work without credentials |
| `GET /healthz`, `GET /live` | Kubernetes liveness probes |
| `GET /ready` | Kubernetes readiness probes |
| `GET /prometheus` | Public by default; protected when `METRICS_AUTH=true` |
| `OPTIONS *` | CORS preflight must respond before auth headers are available |
The `GET /prometheus` endpoint optionally requires auth when `requireAuthForMetrics: true` is set in the server configuration. This allows Prometheus to scrape without credentials in trusted networks, while requiring auth in public-facing deployments.
**Unauthorized response** (`401`):
```json
{ "ok": false, "error": "Unauthorized" }
```
---
## CORS
Cross-Origin Resource Sharing is configured via the `CORS_ALLOW_ORIGIN` environment variable. By default it is unset, meaning no cross-origin access is granted. Set it explicitly, and only to the origins that need browser access (e.g., `CORS_ALLOW_ORIGIN=https://dashboard.example.com`). See the [Security guide](/security/) for hardening recommendations.
When CORS is configured, all JSON responses include the `Access-Control-Allow-Origin` header. Preflight (`OPTIONS`) requests return:
```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400
```
The `Max-Age: 86400` (24 hours) means browsers cache the preflight response, avoiding repeated OPTIONS requests.
---
## Error Responses
All errors follow a consistent format with appropriate HTTP status codes:
| Code | Meaning | When |
| ----- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `200` | Success | Operation completed successfully |
| `400` | Bad Request | Invalid JSON, missing required fields, validation failure (e.g., queue name too long, priority out of range) |
| `401` | Unauthorized | Missing or invalid Bearer token |
| `404` | Not Found | Job, queue, cron, or webhook not found |
| `429` | Rate Limited | Client exceeded the configured request rate |
| `500` | Internal Error | Unexpected server error (logged server-side) |
**Error response body:**
```json
{ "ok": false, "error": "Queue name contains invalid characters" }
```
**Validation rules applied to all endpoints:**
- **Queue names**: 1-256 characters, alphanumeric + `-_.:`
- **Numeric fields**: Validated for type, range, and finiteness (e.g., `delay` must be 0 to 365 days, `priority` must be -1M to +1M)
- **Job data**: Max 10MB per job payload
- **Job IDs**: UUID v7 format (auto-generated) or custom string (via `jobId` field)
---
## Rate Limiting
HTTP requests are rate-limited per client IP using a **sliding window** algorithm. The client IP is resolved in order: `X-Forwarded-For` header (first IP) > `X-Real-IP` header > `"unknown"`.
| Variable | Default | Description |
| ------------------------- | ------- | --------------------------------------------------- |
| `RATE_LIMIT_WINDOW_MS` | `60000` | Sliding window duration in milliseconds |
| `RATE_LIMIT_MAX_REQUESTS` | `10000` | Maximum requests per window per IP. |
| `RATE_LIMIT_CLEANUP_MS` | `60000` | Interval for cleaning up expired rate limit entries |
When rate limited, the server responds with:
```json
{ "ok": false, "error": "Rate limit exceeded" }
```
Status code: `429`. The client should implement exponential backoff before retrying.
:::note
This is HTTP-level rate limiting per client IP. For per-queue job throughput limiting, use the [Queue Rate Limit](#set-rate-limit) endpoints.
:::
---
## Job Lifecycle
Understanding the job lifecycle is essential for using the API effectively. A job flows through these states: