Download OpenAPI specification:
Forq API
Get application metrics in Prometheus format.
This endpoint is available only if the metrics were enabled at startup via the FORQ_METRICS_ENABLED env var.
Ideally, this endpoint should not be exposed to the public.
The endpoint is protected by the ApiKey authentication mechanism.
The auth secret must be provided via the FORQ_METRICS_AUTH_SECRET env var at startup.
Each request should pass it via the X-API-Key header as ApiKey <FORQ_METRICS_AUTH_SECRET>.
Produce a message to the queue by submitting a JSON payload to the endpoint. The message will be added to the end of the queue.
Queue names must match ^[a-zA-Z0-9._-]{1,64}$ and must not end with the reserved
-dlq suffix - messages enter dead-letter queues only via the failure/expiry paths.
The endpoint is protected by the ApiKey authentication mechanism.
The auth secret must be provided via the FORQ_AUTH_SECRET env var at startup.
Each request should pass it via the X-API-Key header as ApiKey <FORQ_AUTH_SECRET>.
| queue required | string Example: my-queue The name of the queue |
| X-API-Key required | string Example: my-secret API Key authentication. Each request should pass it via the |
Message to produce
| content required | string The content/payload of the message. Must not exceed 256 KB in size. |
| processAfter | integer <int64> Unix timestamp in milliseconds indicating when the message should be processed. If not provided, the message will be available for processing immediately. Must not be in the past, or more than 366 days in the future. |
{- "content": "I am going on an adventure!",
- "processAfter": 1700000000000
}{- "code": "bad_request.body.content.exceeds_limit"
}Fetch a message from the queue for processing. If there is no message available just yet, the HTTP long-polling will be used to wait for a message to arrive for up to 30 seconds. If no message arrives within that time, a 204 No Content response will be returned.
Once a message is fetched, it becomes invisible to other consumers for up to 5 minutes while it is being processed, or until it is unacknowledged. If the message is not acknowledged within that time, it becomes visible to other consumers again.
The response carries an opaque delivery receipt that must be echoed back on ack/nack
via the X-Forq-Receipt header.
It is important to explicitly acknowledge or unacknowledge the message after processing it!
The endpoint is protected by the ApiKey authentication mechanism.
The auth secret must be provided via the FORQ_AUTH_SECRET env var at startup
Each request should pass it via the X-API-Key header as ApiKey <FORQ_AUTH_SECRET>.
| queue required | string Example: my-queue The name of the queue |
| X-API-Key required | string Example: my-secret API Key authentication. Each request should pass it via the |
{- "id": "0199164b-4dea-78d9-9b4c-c699d5037962",
- "content": "I am going on an adventure!",
- "receipt": "1755366229123"
}Acknowledge a message after successful processing to remove it from the queue permanently.
The delivery receipt returned by the consume endpoint must be passed via the X-Forq-Receipt header.
The receipt fences the acknowledgment to that exact delivery: if the message exceeded the
5-minute visibility timeout and was redelivered to another consumer, the stale acknowledgment
returns a 404 Not Found instead of affecting the other consumer's delivery.
A 404 is also returned if the message was already acknowledged or does not exist.
The endpoint is protected by the ApiKey authentication mechanism.
The auth secret must be provided via the FORQ_AUTH_SECRET env var at startup.
Each request should pass it via the X-API-Key header as ApiKey <FORQ_AUTH_SECRET>.
| queue required | string Example: my-queue The name of the queue |
| messageId required | string <uuid> Example: 0199164b-4dea-78d9-9b4c-c699d5037962 The unique identifier of the message in the UUID v7 format |
| X-API-Key required | string Example: my-secret API Key authentication. Each request should pass it via the |
| X-Forq-Receipt required | string Example: 1755366229123 The opaque delivery receipt returned by the consume endpoint for this message. Fences the ack/nack to that exact delivery. Do not parse it. |
{- "code": "bad_request.body.content.exceeds_limit"
}Unacknowledge a message after failed processing to make it visible to other consumers after the backoff interval (depends on the number of previous attempts). If the max number of attempts is reached, the message is moved to the dead-letter queue (DLQ), and should be either consumed from there, or processed manually via the Admin UI.
The delivery receipt returned by the consume endpoint must be passed via the X-Forq-Receipt header.
The receipt fences the unacknowledgment to that exact delivery: if the message exceeded the
5-minute visibility timeout and was redelivered to another consumer, the stale unacknowledgment
returns a 404 Not Found instead of resetting the other consumer's delivery.
A 404 is also returned if the message is not found in the DB.
The endpoint is protected by the ApiKey authentication mechanism.
The auth secret must be provided via the FORQ_AUTH_SECRET env var at startup.
Each request should pass it via the X-API-Key header as ApiKey <FORQ_AUTH_SECRET>.
| queue required | string Example: my-queue The name of the queue |
| messageId required | string <uuid> Example: 0199164b-4dea-78d9-9b4c-c699d5037962 The unique identifier of the message in the UUID v7 format |
| X-API-Key required | string Example: my-secret API Key authentication. Each request should pass it via the |
| X-Forq-Receipt required | string Example: 1755366229123 The opaque delivery receipt returned by the consume endpoint for this message. Fences the ack/nack to that exact delivery. Do not parse it. |
{- "code": "bad_request.body.content.exceeds_limit"
}