{ "openapi": "3.1.0", "info": { "title": "SimpleQ API", "version": "0.0.1", "description": "The managed job queue for AI and API-heavy backends. POST a job (REST or SDK) and SimpleQ delivers it to your webhook with retries, backoff, per-queue rate limiting, backpressure (429/503/529 defer without burning a retry), a dead-letter queue, and ack mode for long-running work — your code runs unchanged." }, "servers": [ { "url": "https://api.simpleq.io", "description": "API URL" } ], "tags": [ { "name": "Jobs", "description": "Publish jobs, check status, and retry failures." }, { "name": "Queues", "description": "Create queues and manage their config." }, { "name": "DLQ", "description": "Inspect and retry dead-lettered jobs." }, { "name": "Ack mode", "description": "Async acknowledgement, defer, and nack for long-running or backpressured consumers." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sq_live_...", "description": "SimpleQ API key. Get one from the dashboard under API Keys." } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/queues/{queueName}/jobs": { "post": { "summary": "Publish a job", "description": "Queues a job for delivery to the queue’s webhook. If `idempotencyKey` matches a previously published job, returns the existing job (200) instead of creating a duplicate.", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The queue name (URL-safe)" }, "required": true, "description": "The queue name (URL-safe)", "name": "queueName", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "additionalProperties": {}, "description": "Arbitrary JSON object delivered as-is to your webhook. SimpleQ does not inspect or validate the contents." }, "idempotencyKey": { "type": "string", "maxLength": 255, "description": "Optional key for deduplication. Publishing twice with the same key returns the original job instead of creating a duplicate." }, "delay": { "type": "number", "minimum": 0, "maximum": 86400, "description": "Delay delivery by this many seconds (max 86400 = 24h). Decimals allowed." } }, "required": [ "payload" ] } } } }, "responses": { "200": { "description": "Idempotent hit — existing job returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ], "description": "`pending` for a newly created job (201). An idempotent hit (200) returns the existing job, which may be in any status." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "status", "createdAt" ] } } } }, "201": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ], "description": "`pending` for a newly created job (201). An idempotent hit (200) returns the existing job, which may be in any status." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "status", "createdAt" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Free-plan monthly attempt limit reached — publishing resumes next cycle or after upgrading. Never sent to paid plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues": { "get": { "summary": "List queues", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Array of queues (signingSecret omitted)", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "name": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "maxAttempts": { "type": "integer", "minimum": 1 }, "maxDefers": { "type": "integer", "minimum": 0, "description": "Max backpressure holds before a job dead-letters." }, "concurrency": { "type": "integer", "minimum": 1 }, "dlqEnabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "standard", "ack" ] }, "rateLimitMax": { "type": [ "integer", "null" ] }, "rateLimitWindow": { "type": "number", "description": "Seconds" }, "ackTimeout": { "type": "number", "description": "Seconds" }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ] }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ] }, "backoffDelay": { "type": "number", "description": "Seconds" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "name", "webhookUrl", "maxAttempts", "maxDefers", "concurrency", "dlqEnabled", "mode", "rateLimitMax", "rateLimitWindow", "ackTimeout", "ackTimeoutAction", "backoffType", "backoffDelay", "createdAt" ] } } } } } } }, "post": { "summary": "Create a queue", "description": "Creates a queue and generates a `signingSecret` (returned once on creation). Supports named templates that prefill defaults: `anthropic`, `openai`. Explicit fields override template values.", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9-_]+$" }, "webhookUrl": { "type": "string", "format": "uri" }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 25, "default": 3 }, "maxDefers": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 50 }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 }, "dlqEnabled": { "type": "boolean", "default": true }, "mode": { "type": "string", "enum": [ "standard", "ack" ], "default": "standard" }, "rateLimitMax": { "type": [ "integer", "null" ], "minimum": 1, "default": null }, "rateLimitWindow": { "type": "number", "minimum": 0.001, "maximum": 3600, "default": 60 }, "ackTimeout": { "type": "number", "minimum": 0.001, "maximum": 86400, "default": 300 }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ], "default": "retry" }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ], "default": "exponential" }, "backoffDelay": { "type": "number", "minimum": 0, "maximum": 3600, "default": 2 }, "template": { "type": "string", "enum": [ "anthropic", "openai" ], "description": "Optional. Prefills queue defaults from a named template. Explicit fields override the template values." } }, "required": [ "name", "webhookUrl" ] } } } }, "responses": { "201": { "description": "Queue created (signingSecret included)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "name": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "signingSecret": { "type": "string", "description": "Returned only in this creation response — store it now; it is never shown again." }, "maxAttempts": { "type": "integer", "minimum": 1 }, "maxDefers": { "type": "integer", "minimum": 0, "description": "Max backpressure holds before a job dead-letters." }, "concurrency": { "type": "integer", "minimum": 1 }, "dlqEnabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "standard", "ack" ] }, "rateLimitMax": { "type": [ "integer", "null" ] }, "rateLimitWindow": { "type": "number", "description": "Seconds" }, "ackTimeout": { "type": "number", "description": "Seconds" }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ] }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ] }, "backoffDelay": { "type": "number", "description": "Seconds" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "name", "webhookUrl", "signingSecret", "maxAttempts", "maxDefers", "concurrency", "dlqEnabled", "mode", "rateLimitMax", "rateLimitWindow", "ackTimeout", "ackTimeoutAction", "backoffType", "backoffDelay", "createdAt" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit exceeded (maxAttempts/maxDefers ceiling or queue count cap)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues/{id}": { "get": { "summary": "Get a queue", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Queue (signingSecret omitted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "name": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "maxAttempts": { "type": "integer", "minimum": 1 }, "maxDefers": { "type": "integer", "minimum": 0, "description": "Max backpressure holds before a job dead-letters." }, "concurrency": { "type": "integer", "minimum": 1 }, "dlqEnabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "standard", "ack" ] }, "rateLimitMax": { "type": [ "integer", "null" ] }, "rateLimitWindow": { "type": "number", "description": "Seconds" }, "ackTimeout": { "type": "number", "description": "Seconds" }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ] }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ] }, "backoffDelay": { "type": "number", "description": "Seconds" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "name", "webhookUrl", "maxAttempts", "maxDefers", "concurrency", "dlqEnabled", "mode", "rateLimitMax", "rateLimitWindow", "ackTimeout", "ackTimeoutAction", "backoffType", "backoffDelay", "createdAt" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "put": { "summary": "Update queue config", "description": "Partial update. `name` cannot be changed after creation.", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri" }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 25, "default": 3 }, "maxDefers": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 50 }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 }, "dlqEnabled": { "type": "boolean", "default": true }, "mode": { "type": "string", "enum": [ "standard", "ack" ], "default": "standard" }, "rateLimitMax": { "type": [ "integer", "null" ], "minimum": 1, "default": null }, "rateLimitWindow": { "type": "number", "minimum": 0.001, "maximum": 3600, "default": 60 }, "ackTimeout": { "type": "number", "minimum": 0.001, "maximum": 86400, "default": 300 }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ], "default": "retry" }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ], "default": "exponential" }, "backoffDelay": { "type": "number", "minimum": 0, "maximum": 3600, "default": 2 } } } } } }, "responses": { "200": { "description": "Updated queue (signingSecret omitted — it is returned only on creation)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "name": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "maxAttempts": { "type": "integer", "minimum": 1 }, "maxDefers": { "type": "integer", "minimum": 0, "description": "Max backpressure holds before a job dead-letters." }, "concurrency": { "type": "integer", "minimum": 1 }, "dlqEnabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "standard", "ack" ] }, "rateLimitMax": { "type": [ "integer", "null" ] }, "rateLimitWindow": { "type": "number", "description": "Seconds" }, "ackTimeout": { "type": "number", "description": "Seconds" }, "ackTimeoutAction": { "type": "string", "enum": [ "retry", "dead" ] }, "backoffType": { "type": "string", "enum": [ "fixed", "exponential" ] }, "backoffDelay": { "type": "number", "description": "Seconds" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "name", "webhookUrl", "maxAttempts", "maxDefers", "concurrency", "dlqEnabled", "mode", "rateLimitMax", "rateLimitWindow", "ackTimeout", "ackTimeoutAction", "backoffType", "backoffDelay", "createdAt" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Plan limit exceeded (maxAttempts/maxDefers ceiling)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "delete": { "summary": "Delete a queue", "description": "Deletes a queue. The queue stops accepting new jobs and the name becomes available to re-use immediately. Existing jobs remain retrievable by job ID for inspection.", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" } ], "responses": { "204": { "description": "Queue deleted" }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues/{id}/jobs": { "get": { "summary": "List jobs in a queue", "tags": [ "Queues" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Paginated jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "queue": { "type": "string", "description": "The queue name." }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 1 }, "deferCount": { "type": "integer", "minimum": 0, "description": "Backpressure holds spent so far, bounded by the queue's maxDefers — the counter behind a defer_cap_exhausted dead-letter. Defers never count against maxAttempts." }, "idempotencyKey": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": {} }, "scheduledFor": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "lastError": { "type": [ "string", "null" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "success", "failed", "nacked", "deferred" ] }, "error": { "type": [ "string", "null" ] }, "webhookStatusCode": { "type": [ "integer", "null" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "attempt", "status", "error", "webhookStatusCode", "timestamp" ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "queue", "status", "attempts", "maxAttempts", "deferCount", "idempotencyKey", "payload", "scheduledFor", "lastError", "history", "createdAt", "completedAt" ] } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 } }, "required": [ "jobs", "total", "page", "limit" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues/{id}/dlq": { "get": { "summary": "List dead-letter jobs", "tags": [ "DLQ" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "boolean", "null" ] }, "required": false, "name": "includeReplayed", "in": "query" } ], "responses": { "200": { "description": "Paginated DLQ entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "originalJobId": { "type": "string", "description": "The job this entry was dead-lettered from." }, "queue": { "type": "string", "description": "The queue name." }, "payload": { "type": "object", "additionalProperties": {} }, "history": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "success", "failed", "nacked", "deferred" ] }, "error": { "type": [ "string", "null" ] }, "webhookStatusCode": { "type": [ "integer", "null" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "attempt", "status", "error", "webhookStatusCode", "timestamp" ] } }, "deadAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "replayedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" }, "replayedJobId": { "type": [ "string", "null" ], "description": "24-character hex ID" } }, "required": [ "id", "originalJobId", "queue", "payload", "history", "deadAt", "replayedAt", "replayedJobId" ] } }, "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 } }, "required": [ "jobs", "total", "page", "limit" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "410": { "description": "Queue has been deleted; its dead-letter jobs are gone", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues/{id}/dlq/{jobId}/replay": { "post": { "summary": "Replay a dead-lettered job", "tags": [ "DLQ" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "DLQ entry ID" }, "required": true, "description": "DLQ entry ID", "name": "jobId", "in": "path" } ], "responses": { "201": { "description": "New job created from DLQ entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ], "description": "`pending` for a newly created job (201). An idempotent hit (200) returns the existing job, which may be in any status." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "status", "createdAt" ] } } } }, "402": { "description": "Free-plan monthly attempt limit reached — replays mint new billable jobs, so they share the publish gate. Never sent to paid plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Queue or DLQ job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "DLQ job already replayed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "replayedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "replayedJobId": { "type": "string", "description": "24-character hex ID" } }, "required": [ "error", "replayedAt", "replayedJobId" ] } } } }, "410": { "description": "Queue has been deleted; its dead-letter jobs are gone", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/queues/{id}/dlq/replay": { "post": { "summary": "Bulk replay DLQ jobs", "description": "Retries up to 1000 DLQ jobs at once. Provide either `jobIds: string[]` or `all: true`.", "tags": [ "DLQ" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Queue ID" }, "required": true, "description": "Queue ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "all": { "type": "boolean", "enum": [ true ] } }, "required": [ "all" ], "additionalProperties": false }, { "type": "object", "properties": { "jobIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "jobIds" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Bulk replay result", "content": { "application/json": { "schema": { "type": "object", "properties": { "replayed": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "capped": { "type": "boolean" } }, "required": [ "replayed", "skipped", "capped" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Free-plan monthly attempt limit reached — replays mint new billable jobs, so they share the publish gate. Never sent to paid plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Queue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "410": { "description": "Queue has been deleted; its dead-letter jobs are gone", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/jobs/{id}": { "get": { "summary": "Get job status", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Job ID" }, "required": true, "description": "Job ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Job document", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "queue": { "type": "string", "description": "The queue name." }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_ack", "completed", "dead" ] }, "attempts": { "type": "integer", "minimum": 0 }, "maxAttempts": { "type": "integer", "minimum": 1 }, "deferCount": { "type": "integer", "minimum": 0, "description": "Backpressure holds spent so far, bounded by the queue's maxDefers — the counter behind a defer_cap_exhausted dead-letter. Defers never count against maxAttempts." }, "idempotencyKey": { "type": [ "string", "null" ] }, "payload": { "type": "object", "additionalProperties": {} }, "scheduledFor": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "lastError": { "type": [ "string", "null" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "success", "failed", "nacked", "deferred" ] }, "error": { "type": [ "string", "null" ] }, "webhookStatusCode": { "type": [ "integer", "null" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "attempt", "status", "error", "webhookStatusCode", "timestamp" ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 timestamp" } }, "required": [ "id", "queue", "status", "attempts", "maxAttempts", "deferCount", "idempotencyKey", "payload", "scheduledFor", "lastError", "history", "createdAt", "completedAt" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/jobs/{id}/ack": { "post": { "summary": "Acknowledge a job (ack-mode queues only)", "description": "Signals successful completion of a job in `awaiting_ack`. Only valid for queues with `mode: \"ack\"`.", "tags": [ "Ack mode" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Job ID" }, "required": true, "description": "Job ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Ack accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "accepted" ] } } } }, "400": { "description": "Job is not awaiting ack, or queue does not use ack mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/jobs/{id}/nack": { "post": { "summary": "Signal failure for a job (ack-mode queues only)", "description": "Marks an `awaiting_ack` job as failed. `retryable: true` re-queues with backoff; `retryable: false` dead-letters immediately.", "tags": [ "Ack mode" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Job ID" }, "required": true, "description": "Job ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "retryable": { "type": "boolean", "default": true }, "reason": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Nack accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "accepted" ] } } } }, "400": { "description": "Validation error, job not awaiting ack, or queue not in ack mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/jobs/{id}/defer": { "post": { "summary": "Apply backpressure (ack-mode queues only)", "description": "Holds an `awaiting_ack` job for `retryAfter` seconds, then redelivers — without burning an attempt. Use when a downstream returns 429/503/529.", "tags": [ "Ack mode" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Job ID" }, "required": true, "description": "Job ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "retryAfter": { "type": "number", "minimum": 0 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "retryAfter" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Defer accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "24-character hex ID" }, "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "accepted" ] } } } }, "400": { "description": "Validation error, job not awaiting ack, or queue not in ack mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "formErrors": { "type": "array", "items": { "type": "string" } }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "formErrors", "fieldErrors" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } } }, "webhooks": { "job-delivery": { "post": { "summary": "Job delivery (outbound)", "description": "The POST SimpleQ makes to a queue's `webhookUrl` when a job is ready. Signed with `x-simpleq-signature: sha256=` — an HMAC-SHA256 of the raw body, keyed with the queue's `signingSecret`. Verify before processing. 15-second response timeout in standard mode.", "tags": [ "Jobs" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The job ID. Use it for the ack-mode callbacks and as a dedupe key." }, "queue": { "type": "string", "description": "The queue name. Useful when one worker endpoint serves multiple queues." }, "payload": { "type": "object", "additionalProperties": {}, "description": "Your data, exactly as published — delivered verbatim." }, "attempt": { "type": "integer", "minimum": 1, "description": "Which delivery attempt this is, starting at 1." }, "maxAttempts": { "type": "integer", "minimum": 1, "description": "The queue's configured maximum attempts. When attempt === maxAttempts, a non-2xx response dead-letters the job (if the DLQ is enabled)." }, "deferCount": { "type": "integer", "minimum": 0, "description": "How many times this job has been held by backpressure so far. Defers never count against maxAttempts. Use it to apply your own defer cap (e.g. nack after N holds)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the job was originally published. Use it to detect stale work." } }, "required": [ "id", "queue", "payload", "attempt", "maxAttempts", "deferCount", "createdAt" ] } } } }, "responses": { "200": { "description": "Standard mode: job completed. Ack mode: job moves to awaiting_ack and waits for the /ack, /nack, or /defer callback." }, "429": { "description": "Backpressure (also 503/529): held and redelivered after `Retry-After` seconds (60s fallback) without burning an attempt." }, "500": { "description": "Any other non-2xx or timeout: a failed attempt — retried with backoff up to maxAttempts, then dead-lettered." } } } } } }