# 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:**

```json
{ "action": "create" }
```

**Response `200 OK`:**

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

---

### send

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

**Request body:**

```json
{
  "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`:**

```json
{ "msg_id": 12345 }
```

---

### read

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

**Request body:**

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

**Response `200 OK`:**

```json
{
  "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:**

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

**Response `200 OK`:**

```json
{ "archived": true }
```

---

### delete

Permanently delete a message.

**Request body:**

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

**Response `200 OK`:**

```json
{ "deleted": true }
```

---

### purge

Delete all messages in the queue.

**Request body:**

```json
{ "action": "purge" }
```

**Response `200 OK`:**

```json
{ "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.