API Reference

API TLDR

Authentication#

All API endpoints require authentication via the X-API-Key header:

X-API-Key: your-secret-token

Message Operations#

Produce Message#

Send a message to a queue.

POST /api/v1/queues/{queue}/messages

Request Body:

{
  "content": "Your message content (256KB max)",
  "processAfter": 1757875397418 // Optional: delay processing
}

Response:

204 No Content empty body

Consume Message#

Long-poll for the next available message (30s timeout).

GET /api/v1/queues/{queue}/messages

Response:

{
  "id": "0199164b-4dea-78d9-9b4c-c699d5037962",
  "content": "Your message content (256KB max)"
}

Acknowledge Message#

Mark a message as successfully processed.

POST /api/v1/queues/{queue}/messages/{messageId}/ack

Response:

204 No Content empty body

Negative Acknowledge#

Mark a message as failed (will retry with backoff).

POST /api/v1/queues/{queue}/messages/{messageId}/nack

Response:

204 No Content empty body

Error Handling#

All endpoints return appropriate HTTP status codes:

• 200/204 - Success
• 400 - Bad Request (invalid JSON, content too large)
• 401 - Unauthorized (missing or invalid API key)
• 404 - Not Found (queue or message not found)
• 500 - Internal Server Error

Rate Limits#

Forq does not implement built-in rate limiting. Use nginx, Cloudflare, or load balancers for rate limiting in production.