Queues

Scribase environments include a durable message queue primitive backed by Postgres. Queues are created per-environment and support at-least-once delivery with visibility timeouts.

Endpoint

All queue operations use a single route:

POST /v1/organizations/{org}/projects/{project}/environments/{env}/queues/{queue}

The action travels in the request body.

Actions

create

Create a new queue.

Request body:

{ "action": "create" }

Response 200 OK:

{ "queue": "events", "created": true }

send

Send a message. The message field must be valid JSON.

Request body:

{
  "action": "send",
  "message": { "type": "order.placed", "id": 42 },
  "delay_seconds": 0
}

delay_seconds is optional (default: 0). The message becomes visible after the delay.

Response 200 OK:

{ "msg_id": 12345 }

read

Read one or more messages. Messages become invisible during the visibility timeout — other readers will not see them.

Request body:

{
  "action": "read",
  "quantity": 1,
  "visibility_timeout_seconds": 30
}

Response 200 OK:

{
  "messages": [
    {
      "msg_id": 12345,
      "message": { "type": "order.placed", "id": 42 },
      "enqueued_at": "2026-01-01T00:00:00Z",
      "read_count": 1
    }
  ]
}

archive

Archive a message after processing. The message is retained for audit.

Request body:

{ "action": "archive", "msg_id": 12345 }

Response 200 OK:

{ "archived": true }

delete

Permanently delete a message.

Request body:

{ "action": "delete", "msg_id": 12345 }

Response 200 OK:

{ "deleted": true }

purge

Delete all messages in the queue.

Request body:

{ "action": "purge" }

Response 200 OK:

{ "purged_count": 42 }

Delivery semantics

• At-least-once delivery: A message is re-delivered if it is not archived or deleted within its visibility timeout.
• Ordering: Messages are returned roughly in FIFO order but strict ordering is not guaranteed under concurrent readers.
• read_count: The number of times a message has been delivered. Use this to detect poison messages and route them to a dead-letter queue.