queen-mq 0.1.0 → 0.1.2

package/API.md

@@ -1,1056 +1,1108 @@
-# Queen V2 API Documentation
+# Queen Message Queue - API Documentation
 
-## Overview
+**Base URL:** `http://localhost:6632`
 
-Queen V2 is a high-performance message queue system with a two-tier architecture:
-- **Queues**: Top-level organizational units
-- **Partitions**: Subdivisions within queues where FIFO ordering is maintained
+**API Version:** v1
 
-Base URL: `http://localhost:6632/api/v1`
-
-## Core Concepts
-
-### Message Flow
-1. Messages are **pushed** to a queue (optionally specifying a partition)
-2. Messages are **popped** from either a specific partition or any partition in a queue
-3. Messages must be **acknowledged** after processing (completed or failed)
-
-### Partitions
-- Every queue automatically has a "Default" partition
-- Additional partitions can be created by pushing messages to them
-- FIFO ordering is maintained within each partition
-- Messages without a specified partition go to "Default"
-
-### Optional Grouping
-- Queues can have optional `namespace` and `task` fields for logical grouping
-- These don't affect the hierarchy but allow filtering operations
+**Date:** October 15, 2025
 
 ---
 
-## API Endpoints
+## Table of Contents
 
-### 1. Push Messages
-**Endpoint:** `POST /api/v1/push`
+1. [Authentication](#authentication)
+2. [Health & Monitoring](#health--monitoring)
+3. [Queue Management](#queue-management)
+4. [Message Operations](#message-operations)
+5. [Resource Queries](#resource-queries)
+6. [Status & Analytics](#status--analytics)
+7. [Error Responses](#error-responses)
 
-Adds one or more messages to queues.
+---
 
-**Request Body:**
-```json
-{
-  "items": [
-    {
-      "queue": "email-queue",           // Required: queue name
-      "partition": "urgent",             // Optional: defaults to "Default"
-      "payload": {                      // Required: message data (JSON)
-        "to": "user@example.com",
-        "subject": "Hello"
-      },
-      "transactionId": "uuid-here"      // Optional: idempotency key
-    }
-  ]
-}
-```
+## Authentication
 
-**Response:**
-```json
-{
-  "messages": [
-    {
-      "id": "018e63b7-6165-453f-88ae-56effa177605",
-      "transactionId": "4dfb0478-655b-4c91-bcd9-b7acacf0400f",
-      "status": "queued"  // or "duplicate" if transactionId exists
-    }
-  ]
-}
-```
+Currently, the Queen API does not require authentication. All endpoints are publicly accessible. CORS is enabled with the following headers:
 
-**Notes:**
-- Supports batch operations (up to 1000 messages)
-- Automatic duplicate detection via transactionId
-- Creates queue/partition if they don't exist
+- `Access-Control-Allow-Origin`: `*`
+- `Access-Control-Allow-Methods`: `GET, POST, PUT, DELETE, OPTIONS`
+- `Access-Control-Allow-Headers`: `Content-Type, Authorization`
 
 ---
 
-### 2. Pop Messages
+## Health & Monitoring
 
-#### 2.1 Pop from Specific Partition
-**Endpoint:** `GET /api/v1/pop/queue/:queue/partition/:partition`
+### GET /health
 
-Retrieves messages from a specific partition.
+**Purpose:** Check server health and get basic performance statistics.
 
-**Query Parameters:**
-- `batch` (integer): Number of messages to retrieve (default: 1)
-- `wait` (boolean): Enable long polling (default: false)
-- `timeout` (integer): Long polling timeout in ms (default: 30000, max: 60000)
+**Authentication:** None
 
-**Example:**
-```
-GET /api/v1/pop/queue/emails/partition/urgent?batch=5&wait=true
-```
+**Query Parameters:** None
 
 **Response:**
 ```json
 {
-  "messages": [
-    {
-      "id": "message-uuid",
-      "transactionId": "transaction-uuid",
-      "queue": "emails",
-      "partition": "urgent",
-      "data": { "to": "user@example.com", "subject": "Alert" },
-      "retryCount": 0,
-      "priority": 0,
-      "createdAt": "2025-10-08T05:12:33.893Z",
-      "lockedAt": null,
-      "options": { "leaseTime": 300, "retryLimit": 3 }
+  "status": "healthy",
+  "uptime": "30s",
+  "connections": 0,
+  "stats": {
+    "requests": 0,
+    "messages": 0,
+    "requestsPerSecond": "0.00",
+    "messagesPerSecond": "0.00",
+    "pool": {
+      "total": 3,
+      "idle": 3,
+      "waiting": 0
     }
-  ]
+  }
 }
 ```
 
-#### 2.2 Pop from Any Partition in Queue
-**Endpoint:** `GET /api/v1/pop/queue/:queue`
-
-Retrieves messages from any available partition in the queue (oldest first).
+**Status Codes:**
+- `200`: Server is healthy
+- `503`: Server is unhealthy
 
-**Query Parameters:** Same as above
+---
 
-**Example:**
-```
-GET /api/v1/pop/queue/emails?batch=10
-```
+### GET /metrics
 
-#### 2.3 Pop with Filters
-**Endpoint:** `GET /api/v1/pop`
+**Purpose:** Get detailed performance metrics for monitoring and observability.
 
-Retrieves messages from queues matching namespace or task filters.
+**Authentication:** None
 
-**Query Parameters:**
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
-- `batch`, `wait`, `timeout`: Same as above
+**Query Parameters:** None
 
-**Example:**
-```
-GET /api/v1/pop?namespace=production&batch=5
-GET /api/v1/pop?task=billing&wait=true
+**Response:**
+```json
+{
+  "uptime": 44.691,
+  "requests": {
+    "total": 0,
+    "rate": 0
+  },
+  "messages": {
+    "total": 0,
+    "rate": 0
+  },
+  "database": {
+    "poolSize": 3,
+    "idleConnections": 3,
+    "waitingRequests": 0
+  },
+  "memory": {
+    "rss": 51740672,
+    "heapTotal": 9224192,
+    "heapUsed": 7700024,
+    "external": 2189469,
+    "arrayBuffers": 103809
+  },
+  "cpu": {
+    "user": 179881,
+    "system": 47586
+  }
+}
 ```
 
-**Response Format:** Same as above
-
 **Status Codes:**
-- `200`: Messages retrieved successfully
-- `204`: No messages available (empty response)
+- `200`: Success
 
 ---
 
-### 3. Acknowledge Messages
+## Queue Management
 
-#### 3.1 Single Acknowledgment
-**Endpoint:** `POST /api/v1/ack`
+### POST /api/v1/configure
 
-Acknowledges a single message as completed or failed.
+**Purpose:** Create or configure a queue with specific settings and partitions.
+
+**Authentication:** None
 
 **Request Body:**
 ```json
 {
-  "transactionId": "4dfb0478-655b-4c91-bcd9-b7acacf0400f",
-  "status": "completed",  // or "failed"
-  "error": "Error message if failed"  // Optional
+  "queue": "test-queue",
+  "partition": "Default",
+  "ttl": 300,
+  "priority": 1,
+  "maxQueueSize": 1000
 }
 ```
 
+**Parameters:**
+- `queue` (string, required): Queue name
+- `partition` (string, optional): Partition name (defaults to "Default")
+- `ttl` (number, optional): Time-to-live in seconds
+- `priority` (number, optional): Queue priority (0-100)
+- `maxQueueSize` (number, optional): Maximum queue size
+- `leaseTime` (number, optional): Lease time for messages in seconds
+- `retryLimit` (number, optional): Maximum retry attempts
+- `retryDelay` (number, optional): Delay between retries in milliseconds
+
 **Response:**
 ```json
 {
-  "transactionId": "4dfb0478-655b-4c91-bcd9-b7acacf0400f",
-  "status": "completed",
-  "acknowledgedAt": "2025-10-08T07:12:47.353Z"
+  "queue": "test-queue",
+  "namespace": null,
+  "task": null,
+  "configured": true,
+  "options": {
+    "leaseTime": 300,
+    "maxSize": 10000,
+    "ttl": 3600,
+    "retryLimit": 3,
+    "retryDelay": 1000,
+    "deadLetterQueue": false,
+    "dlqAfterMaxRetries": false,
+    "priority": 0,
+    "delayedProcessing": 0,
+    "windowBuffer": 0,
+    "retentionSeconds": 0,
+    "completedRetentionSeconds": 0,
+    "retentionEnabled": false
+  },
+  "partition": "Default",
+  "_deprecation_notice": "Partition-level configuration is deprecated. All configuration is now at queue level."
 }
 ```
 
-#### 3.2 Batch Acknowledgment
-**Endpoint:** `POST /api/v1/ack/batch`
+**Status Codes:**
+- `201`: Queue configured successfully
+- `400`: Invalid request body
+- `500`: Internal server error
+
+---
+
+## Message Operations
+
+### POST /api/v1/push
 
-Acknowledges multiple messages at once.
+**Purpose:** Push one or more messages to a queue.
+
+**Authentication:** None
 
 **Request Body:**
 ```json
 {
-  "acknowledgments": [
-    {
-      "transactionId": "uuid-1",
-      "status": "completed"
-    },
+  "items": [
     {
-      "transactionId": "uuid-2",
-      "status": "failed",
-      "error": "Processing error"
+      "queue": "test-queue",
+      "partition": "Default",
+      "payload": {
+        "message": "Hello World"
+      },
+      "ttl": 300,
+      "priority": 1,
+      "traceId": "optional-trace-id"
     }
   ]
 }
 ```
 
+**Parameters:**
+- `items` (array, required): Array of messages to push
+  - `queue` (string, required): Queue name
+  - `partition` (string, optional): Partition name (defaults to "Default")
+  - `payload` (object, required): Message payload (any JSON object)
+  - `ttl` (number, optional): Message time-to-live in seconds
+  - `priority` (number, optional): Message priority
+  - `traceId` (string, optional): Trace ID for distributed tracing
+
 **Response:**
 ```json
 {
-  "processed": 2,
-  "results": [
-    { "transactionId": "uuid-1", "status": "completed" },
-    { "transactionId": "uuid-2", "status": "retry_scheduled", "retryCount": 1 }
+  "messages": [
+    {
+      "id": "0199e688-1857-7462-81ea-b87975de7e95",
+      "transactionId": "0199e688-1857-7462-81ea-b4fe7532bbde",
+      "traceId": null,
+      "status": "queued"
+    }
   ]
 }
 ```
 
-**Notes:**
-- Failed messages are automatically retried based on partition's `retryLimit`
-- After max retries, messages can be moved to dead letter queue
+**Status Codes:**
+- `201`: Messages pushed successfully
+- `400`: Invalid request body
+- `500`: Internal server error
 
 ---
 
-### 4. Configure Queue
-**Endpoint:** `POST /api/v1/configure`
+### GET /api/v1/pop/queue/:queue/partition/:partition
 
-Configures options for a queue. All configuration is now at the queue level - partitions are simple FIFO containers.
+**Purpose:** Pop messages from a specific queue and partition.
 
-**Request Body:**
-```json
-{
-  "queue": "notifications",
-  "partition": "critical",  // DEPRECATED: Ignored but accepted for backward compatibility
-  "options": {
-    "leaseTime": 600,       // Seconds before message lease expires
-    "retryLimit": 5,        // Max retry attempts
-    "priority": 10,         // Queue priority (higher = processed first)
-    "maxSize": 10000,       // Max messages in queue
-    "ttl": 3600,           // Time to live in seconds
-    "dlqAfterMaxRetries": true,  // Move to DLQ after max retries
-    "delayedProcessing": 0,      // Delay before messages are available (seconds)
-    "windowBuffer": 0,            // Buffer window for message processing (seconds)
-    "retentionSeconds": 0,       // Auto-delete pending messages after X seconds
-    "completedRetentionSeconds": 0, // Auto-delete completed messages after X seconds
-    "retentionEnabled": false,   // Enable retention policies
-    "encryptionEnabled": false,  // Enable message encryption
-    "maxWaitTimeSeconds": 0      // Max wait time for long polling
-  }
-}
-```
+**Authentication:** None
+
+**Path Parameters:**
+- `queue` (string): Queue name
+- `partition` (string): Partition name
+
+**Query Parameters:**
+- `wait` (boolean, optional): Wait for messages if queue is empty (default: false)
+- `timeout` (number, optional): Wait timeout in milliseconds (default: 30000)
+- `batch` (number, optional): Number of messages to pop (default: 1)
+- `consumerGroup` (string, optional): Consumer group name for subscription mode
+- `subscriptionMode` (string, optional): Subscription mode: "earliest", "latest", "timestamp"
+- `subscriptionFrom` (string, optional): Starting point for subscription
 
 **Response:**
 ```json
 {
-  "queue": "notifications",
-  "configured": true,
-  "options": { /* all options with defaults filled */ }
+  "messages": [
+    {
+      "id": "0199e688-1857-7462-81ea-b87975de7e95",
+      "transactionId": "0199e688-1857-7462-81ea-b4fe7532bbde",
+      "traceId": null,
+      "queue": "test-queue",
+      "partition": "Default",
+      "data": {
+        "message": "Hello World"
+      },
+      "payload": {
+        "message": "Hello World"
+      },
+      "retryCount": 0,
+      "priority": "0",
+      "createdAt": "2025-10-15T06:21:42.865Z",
+      "consumerGroup": null
+    }
+  ]
 }
 ```
 
-**Note:** The `partition` parameter in the request is deprecated and ignored. All configuration now applies to the entire queue.
+**Status Codes:**
+- `200`: Messages retrieved successfully
+- `204`: No messages available
+- `500`: Internal server error
 
 ---
 
-### 5. Analytics & Monitoring
+### GET /api/v1/pop/queue/:queue
 
-#### 5.1 Queue Statistics
-**Endpoint:** `GET /api/v1/analytics/queue/:queue`
+**Purpose:** Pop messages from a queue (any partition).
 
-Gets detailed statistics for a specific queue.
+**Authentication:** None
 
-**Response:**
-```json
-{
-  "queue": "emails",
-  "namespace": null,
-  "task": null,
-  "totals": {
-    "pending": 10,
-    "processing": 5,
-    "completed": 100,
-    "failed": 2,
-    "deadLetter": 1,
-    "total": 118
-  },
-  "partitions": [
-    {
-      "name": "Default",
-      "stats": {
-        "pending": 8,
-        "processing": 3,
-        "completed": 80,
-        "failed": 1,
-        "deadLetter": 0,
-        "total": 92
-      }
-    },
-    {
-      "name": "urgent",
-      "stats": {
-        "pending": 2,
-        "processing": 2,
-        "completed": 20,
-        "failed": 1,
-        "deadLetter": 1,
-        "total": 26
-      }
-    }
-  ]
-}
-```
+**Path Parameters:**
+- `queue` (string): Queue name
+
+**Query Parameters:** Same as `/api/v1/pop/queue/:queue/partition/:partition`
+
+**Response:** Same as `/api/v1/pop/queue/:queue/partition/:partition`
 
-#### 5.2 All Queues Overview
-**Endpoint:** `GET /api/v1/analytics/queues`
+**Status Codes:**
+- `200`: Messages retrieved successfully
+- `204`: No messages available
+- `500`: Internal server error
+
+---
 
-Gets statistics for all queues in the system.
+### GET /api/v1/pop
+
+**Purpose:** Pop messages from queues filtered by namespace or task.
+
+**Authentication:** None
 
 **Query Parameters:**
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
+- `namespace` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
+- `wait` (boolean, optional): Wait for messages if queue is empty
+- `timeout` (number, optional): Wait timeout in milliseconds
+- `batch` (number, optional): Number of messages to pop
+- `consumerGroup` (string, optional): Consumer group name
 
-**Response:**
+**Response:** Same as `/api/v1/pop/queue/:queue/partition/:partition`
+
+**Status Codes:**
+- `200`: Messages retrieved successfully
+- `204`: No messages available
+- `500`: Internal server error
+
+---
+
+### POST /api/v1/ack
+
+**Purpose:** Acknowledge a single message as completed or failed.
+
+**Authentication:** None
+
+**Request Body:**
 ```json
 {
-  "queues": [
-    {
-      "queue": "emails",
-      "namespace": "production",
-      "task": "notifications",
-      "partitions": [...],
-      "totals": {...}
-    }
-  ]
+  "transactionId": "0199e688-4d29-7019-bf32-5d4f21306b35",
+  "status": "completed",
+  "error": "optional error message if failed"
 }
 ```
 
-#### 5.3 Queue Depths
-**Endpoint:** `GET /api/v1/analytics/queue-depths`
-
-Gets pending message counts for all queues.
+**Parameters:**
+- `transactionId` (string, required): Transaction ID of the message
+- `status` (string, required): "completed" or "failed"
+- `error` (string, optional): Error message if status is "failed"
+- `consumerGroup` (string, optional): Consumer group name
 
 **Response:**
 ```json
 {
-  "depths": [
-    {
-      "queue": "emails",
-      "depth": 10,        // Total pending
-      "processing": 5,    // Total processing
-      "partitions": [
-        { "name": "Default", "depth": 8, "processing": 3 },
-        { "name": "urgent", "depth": 2, "processing": 2 }
-      ]
-    }
-  ]
+  "status": "completed",
+  "consumerGroup": null,
+  "acknowledgedAt": "2025-10-15T06:22:02.382Z"
 }
 ```
 
-#### 5.4 Throughput Metrics
-**Endpoint:** `GET /api/v1/analytics/throughput`
+**Status Codes:**
+- `200`: Acknowledgment successful
+- `400`: Invalid request body
+- `500`: Internal server error
 
-Gets throughput metrics over the last hour (minute-by-minute).
+---
 
-**Response:**
+### POST /api/v1/ack/batch
+
+**Purpose:** Acknowledge multiple messages in a single request.
+
+**Authentication:** None
+
+**Request Body:**
 ```json
 {
-  "throughput": [
+  "acknowledgments": [
     {
-      "timestamp": "2025-10-08T07:00:00.000Z",
-      "incoming": {
-        "messagesPerMinute": 120,
-        "messagesPerSecond": 2
-      },
-      "completed": {
-        "messagesPerMinute": 115,
-        "messagesPerSecond": 1
-      },
-      "processing": {
-        "messagesPerMinute": 100,
-        "messagesPerSecond": 1
-      },
-      "failed": {
-        "messagesPerMinute": 5,
-        "messagesPerSecond": 0
-      },
-      "lag": {
-        "avgSeconds": 2.5,
-        "avgMilliseconds": 2500,
-        "sampleCount": 115
-      }
+      "transactionId": "0199e688-6c45-769d-921b-527ee7c3d57c",
+      "status": "completed"
+    },
+    {
+      "transactionId": "0199e688-6c45-769d-921b-55f611d0cd5a",
+      "status": "failed",
+      "error": "Test error"
     }
-    // ... 59 more entries
-  ]
+  ],
+  "consumerGroup": "optional-consumer-group"
 }
 ```
 
-#### 5.5 Queue Lag Analysis
-**Endpoint:** `GET /api/v1/analytics/queue-lag`
-
-Gets queue lag metrics based on processing times and current backlog.
-
-**Query Parameters:**
-- `queue` (string): Filter by queue name
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
+**Parameters:**
+- `acknowledgments` (array, required): Array of acknowledgments
+  - `transactionId` (string, required): Transaction ID
+  - `status` (string, required): "completed" or "failed"
+  - `error` (string, optional): Error message if failed
+- `consumerGroup` (string, optional): Consumer group name
 
 **Response:**
 ```json
 {
-  "queues": [
+  "processed": 2,
+  "results": [
     {
-      "queue": "emails",
-      "namespace": "production",
-      "task": "notifications",
-      "partitions": [
-        {
-          "name": "Default",
-          "stats": {
-            "pendingCount": 150,
-            "processingCount": 25,
-            "totalBacklog": 175,
-            "completedMessages": 1250,
-            "avgProcessingTimeSeconds": 2.5,
-            "medianProcessingTimeSeconds": 2.1,
-            "p95ProcessingTimeSeconds": 4.8,
-            "estimatedLagSeconds": 437.5,
-            "medianLagSeconds": 367.5,
-            "p95LagSeconds": 840.0,
-            "estimatedLag": "7m 17s",
-            "medianLag": "6m 7s",
-            "p95Lag": "14m 0s",
-            "avgProcessingTime": "2.5s",
-            "medianProcessingTime": "2.1s",
-            "p95ProcessingTime": "4.8s"
-          }
-        }
-      ],
-      "totals": {
-        "pendingCount": 150,
-        "processingCount": 25,
-        "totalBacklog": 175,
-        "completedMessages": 1250,
-        "avgProcessingTimeSeconds": 2.5,
-        "medianProcessingTimeSeconds": 2.1,
-        "p95ProcessingTimeSeconds": 4.8,
-        "estimatedLagSeconds": 437.5,
-        "medianLagSeconds": 367.5,
-        "p95LagSeconds": 840.0,
-        "estimatedLag": "7m 17s",
-        "medianLag": "6m 7s",
-        "p95Lag": "14m 0s",
-        "avgProcessingTime": "2.5s",
-        "medianProcessingTime": "2.1s",
-        "p95ProcessingTime": "4.8s"
-      }
+      "transactionId": "0199e688-6c45-769d-921b-527ee7c3d57c",
+      "status": "completed"
+    },
+    {
+      "transactionId": "0199e688-6c45-769d-921b-55f611d0cd5a",
+      "status": "failed_dlq"
     }
   ]
 }
 ```
 
-**Lag Calculation:**
-- **Estimated Lag**: `(pending + processing) × average_processing_time`
-- **Median Lag**: `(pending + processing) × median_processing_time`
-- **95th Percentile Lag**: `(pending + processing) × p95_processing_time`
+**Status Codes:**
+- `200`: Batch acknowledgment successful
+- `400`: Invalid request body
+- `500`: Internal server error
 
-**Notes:**
-- Only includes queues with at least 5 completed messages in the last 24 hours
-- Processing times are calculated from `completed_at - created_at` for completed messages
-- Lag represents the estimated time for all current backlog to be processed
+---
 
-#### 5.6 Queue-Specific Stats
-**Endpoint:** `GET /api/v1/analytics/queue-stats`
+### GET /api/v1/messages
 
-Gets statistics with flexible filtering.
+**Purpose:** List messages with optional filters.
+
+**Authentication:** None
 
 **Query Parameters:**
-- `queue` (string): Filter by queue name
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
+- `queue` (string, optional): Filter by queue name
+- `ns` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
+- `status` (string, optional): Filter by status
+- `limit` (number, optional): Number of messages to return (default: 100)
+- `offset` (number, optional): Offset for pagination (default: 0)
 
-**Example:**
-```
-GET /api/v1/analytics/queue-stats?queue=emails
-GET /api/v1/analytics/queue-stats?namespace=production
+**Response:**
+```json
+{
+  "messages": []
+}
 ```
 
-#### 5.6 Filtered Analytics
-**Endpoint:** `GET /api/v1/analytics`
-
-Gets analytics based on namespace or task filters.
+**Note:** This endpoint currently has a database schema issue (`column m.status does not exist`).
 
-**Query Parameters:**
-- `namespace` (string): Get all queues in namespace
-- `task` (string): Get all queues with task
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
 
 ---
 
-### 6. Message Management
+### GET /api/v1/messages/:transactionId
 
-#### 6.1 List Messages
-**Endpoint:** `GET /api/v1/messages`
+**Purpose:** Get details of a specific message by transaction ID.
 
-Lists messages with filtering options.
+**Authentication:** None
 
-**Query Parameters:**
-- `queue` (string): Filter by queue name
-- `partition` (string): Filter by partition name
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
-- `status` (string): Filter by status (pending, processing, completed, failed, dead_letter)
-- `limit` (integer): Max results (default: 100)
-- `offset` (integer): Pagination offset (default: 0)
+**Path Parameters:**
+- `transactionId` (string): Message transaction ID
 
 **Response:**
 ```json
 {
-  "messages": [
-    {
-      "id": "message-uuid",
-      "transactionId": "transaction-uuid",
-      "queuePath": "emails/urgent",
-      "queue": "emails",
-      "partition": "urgent",
-      "namespace": null,
-      "task": null,
-      "payload": {...},
-      "status": "pending",
-      "workerId": null,
-      "createdAt": "2025-10-08T05:12:33.889Z",
-      "lockedAt": null,
-      "completedAt": null,
-      "failedAt": null,
-      "errorMessage": null,
-      "retryCount": 0,
-      "leaseExpiresAt": null
-    }
-  ]
+  "id": "0199e688-1857-7462-81ea-b87975de7e95",
+  "transactionId": "0199e688-1857-7462-81ea-b4fe7532bbde",
+  "queuePath": "test-queue/Default",
+  "queue": "test-queue",
+  "partition": "Default",
+  "namespace": null,
+  "task": null,
+  "payload": {
+    "message": "Hello World"
+  },
+  "createdAt": "2025-10-15T06:21:42.865Z",
+  "queueConfig": {
+    "leaseTime": 300,
+    "retryLimit": 3,
+    "retryDelay": 1000,
+    "ttl": 3600,
+    "priority": 0
+  }
 }
 ```
 
-#### 6.2 Get Single Message
-**Endpoint:** `GET /api/v1/messages/:transactionId`
+**Status Codes:**
+- `200`: Message found
+- `404`: Message not found
+- `500`: Internal server error
+
+---
 
-Gets details of a specific message.
+### DELETE /api/v1/messages/:transactionId
 
-**Response:** Single message object with partition options included
+**Purpose:** Delete a specific message by transaction ID.
 
-#### 6.3 Delete Message
-**Endpoint:** `DELETE /api/v1/messages/:transactionId`
+**Authentication:** None
 
-Permanently deletes a message.
+**Path Parameters:**
+- `transactionId` (string): Message transaction ID
 
 **Response:**
 ```json
 {
   "deleted": true,
-  "transactionId": "transaction-uuid"
+  "transactionId": "0199e688-1857-7462-81ea-b4fe7532bbde"
 }
 ```
 
-#### 6.4 Retry Failed Message
-**Endpoint:** `POST /api/v1/messages/:transactionId/retry`
+**Status Codes:**
+- `200`: Message deleted
+- `404`: Message not found
+- `500`: Internal server error
+
+---
+
+### POST /api/v1/messages/:transactionId/retry
 
-Resets a failed message to pending for retry.
+**Purpose:** Retry a failed message.
+
+**Authentication:** None
+
+**Path Parameters:**
+- `transactionId` (string): Message transaction ID
 
 **Response:**
 ```json
 {
   "retried": true,
-  "transactionId": "transaction-uuid"
+  "transactionId": "0199e688-a908-726e-9ca2-a2a9b312684d"
 }
 ```
 
-#### 6.5 Move to Dead Letter Queue
-**Endpoint:** `POST /api/v1/messages/:transactionId/dlq`
+**Status Codes:**
+- `200`: Message retried
+- `500`: Internal server error
+
+---
+
+### POST /api/v1/messages/:transactionId/dlq
+
+**Purpose:** Move a message to the dead letter queue.
 
-Moves a failed message to the dead letter queue.
+**Authentication:** None
+
+**Path Parameters:**
+- `transactionId` (string): Message transaction ID
 
 **Response:**
 ```json
 {
   "movedToDLQ": true,
-  "transactionId": "transaction-uuid"
+  "transactionId": "0199e688-a908-726e-9ca2-a2a9b312684d"
 }
 ```
 
-#### 6.6 Get Related Messages
-**Endpoint:** `GET /api/v1/messages/:transactionId/related`
+**Status Codes:**
+- `200`: Message moved to DLQ
+- `500`: Internal server error
 
-Gets messages from the same partition within 1 hour of the specified message.
+---
 
-**Response:**
-```json
-{
-  "messages": [
-    {
-      "transactionId": "related-uuid",
-      "status": "completed",
-      "createdAt": "2025-10-08T05:10:00.000Z",
-      "payload": {...}
-    }
-  ]
-}
-```
+### GET /api/v1/messages/:transactionId/related
 
-#### 6.7 Clear Queue
-**Endpoint:** `DELETE /api/v1/queues/:queue/clear`
+**Purpose:** Get messages related to a specific message (e.g., by trace ID).
 
-Deletes all messages from a queue or specific partition.
+**Authentication:** None
 
-**Query Parameters:**
-- `partition` (string): Clear specific partition only
+**Path Parameters:**
+- `transactionId` (string): Message transaction ID
 
 **Response:**
 ```json
 {
-  "cleared": true,
-  "count": 25,
-  "queue": "emails",
-  "partition": "all"  // or specific partition name
+  "messages": []
 }
 ```
 
----
+**Note:** This endpoint currently has a database schema issue.
 
-### 7. System Health & Metrics
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
 
-#### 7.1 Health Check
-**Endpoint:** `GET /health`
+---
 
-Checks system health and basic statistics.
+### DELETE /api/v1/queues/:queue/clear
 
-**Response:**
-```json
-{
-  "status": "healthy",
-  "uptime": "3600s",
-  "connections": 5,
-  "stats": {
-    "requests": 1000,
-    "messages": 5000,
-    "requestsPerSecond": "0.28",
-    "messagesPerSecond": "1.39",
-    "pool": {
-      "total": 20,
-      "idle": 15,
-      "waiting": 0
-    }
-  }
-}
-```
+**Purpose:** Clear all messages from a queue or specific partition.
 
-#### 7.2 Detailed Metrics
-**Endpoint:** `GET /metrics`
+**Authentication:** None
 
-Gets detailed performance metrics.
+**Path Parameters:**
+- `queue` (string): Queue name
+
+**Query Parameters:**
+- `partition` (string, optional): Partition name to clear (if omitted, clears all partitions)
 
 **Response:**
 ```json
 {
-  "uptime": 3600,
-  "requests": {
-    "total": 1000,
-    "rate": 0.28
-  },
-  "messages": {
-    "total": 5000,
-    "rate": 1.39
-  },
-  "database": {
-    "poolSize": 20,
-    "idleConnections": 15,
-    "waitingRequests": 0
-  },
-  "memory": {
-    "rss": 104857600,
-    "heapTotal": 73728000,
-    "heapUsed": 45678900,
-    "external": 2345678,
-    "arrayBuffers": 123456
-  },
-  "cpu": {
-    "user": 1234567,
-    "system": 234567
-  }
+  "cleared": true,
+  "count": 6,
+  "queue": "test-queue",
+  "partition": "Default"
 }
 ```
 
----
+**Status Codes:**
+- `200`: Queue cleared
+- `500`: Internal server error
 
-## Resource Management
+---
 
-### 8. Resources API
+## Resource Queries
 
-These endpoints provide information about queues, partitions, and system structure for frontend displays.
+### GET /api/v1/resources/queues
 
-#### 8.1 List All Queues
-**Endpoint:** `GET /api/v1/resources/queues`
+**Purpose:** Get a list of all queues with their statistics.
 
-Gets all queues with summary information.
+**Authentication:** None
 
 **Query Parameters:**
-- `namespace` (string): Filter by namespace
-- `task` (string): Filter by task
+- `namespace` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
 
 **Response:**
 ```json
 {
   "queues": [
     {
-      "id": "queue-uuid",
-      "name": "emails",
+      "id": "03093457-e6f6-4e5f-869b-045a6916fdff",
+      "name": "test-queue",
       "namespace": null,
       "task": null,
-      "createdAt": "2025-10-08T05:13:37.528Z",
-      "partitions": 3,
+      "createdAt": "2025-10-15T06:21:42.034Z",
+      "partitions": 1,
       "messages": {
-        "total": 100,
-        "pending": 20,
-        "processing": 5
+        "total": 0,
+        "pending": 2,
+        "processing": 0
       }
     }
   ]
 }
 ```
 
-#### 8.2 Get Queue Details
-**Endpoint:** `GET /api/v1/resources/queues/:queue`
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
+---
+
+### GET /api/v1/resources/queues/:queue
 
-Gets detailed information about a specific queue including all partitions.
+**Purpose:** Get detailed information about a specific queue.
+
+**Authentication:** None
+
+**Path Parameters:**
+- `queue` (string): Queue name
 
 **Response:**
 ```json
 {
-  "id": "queue-uuid",
-  "name": "emails",
+  "id": "03093457-e6f6-4e5f-869b-045a6916fdff",
+  "name": "test-queue",
   "namespace": null,
   "task": null,
-  "createdAt": "2025-10-08T05:13:37.528Z",
+  "createdAt": "2025-10-15T06:21:42.034Z",
   "partitions": [
     {
-      "id": "partition-uuid",
-      "name": "urgent",
-      "priority": 10,
-      "options": {
-        "leaseTime": 300,
-        "retryLimit": 3
-      },
-      "createdAt": "2025-10-08T05:13:37.541Z",
+      "id": "7a30d768-7eb7-40dd-ade9-8afb20c18591",
+      "name": "Default",
+      "createdAt": "2025-10-15T06:21:42.865Z",
       "stats": {
-        "total": 50,
-        "pending": 10,
-        "processing": 2,
-        "completed": 35,
-        "failed": 3,
+        "total": 0,
+        "pending": 2,
+        "processing": 0,
+        "completed": 3,
+        "failed": 0,
         "deadLetter": 0
       },
-      "oldestMessage": "2025-10-08T05:00:00.000Z",
-      "newestMessage": "2025-10-08T07:30:00.000Z"
+      "oldestMessage": null,
+      "newestMessage": null
     }
   ],
   "totals": {
-    "total": 100,
-    "pending": 20,
-    "processing": 5,
-    "completed": 70,
-    "failed": 5,
+    "total": 0,
+    "pending": 2,
+    "processing": 0,
+    "completed": 3,
+    "failed": 0,
     "deadLetter": 0
   }
 }
 ```
 
-#### 8.3 List All Partitions
-**Endpoint:** `GET /api/v1/resources/partitions`
+**Status Codes:**
+- `200`: Success
+- `404`: Queue not found
+- `500`: Internal server error
+
+---
+
+### DELETE /api/v1/resources/queues/:queue
+
+**Purpose:** Delete a queue and all its messages.
 
-Gets all partitions across all queues.
+**Authentication:** None
+
+**Path Parameters:**
+- `queue` (string): Queue name
+
+**Response:**
+```json
+{
+  "deleted": true,
+  "queue": "test-queue"
+}
+```
+
+**Status Codes:**
+- `200`: Queue deleted
+- `500`: Internal server error
+
+---
+
+### GET /api/v1/resources/partitions
+
+**Purpose:** Get a list of partitions across all queues.
+
+**Authentication:** None
 
 **Query Parameters:**
-- `queue` (string): Filter by queue name
-- `minDepth` (integer): Only show partitions with at least this many pending messages
+- `queue` (string, optional): Filter by queue name
+- `minDepth` (number, optional): Filter partitions with at least this many messages
 
 **Response:**
 ```json
 {
   "partitions": [
     {
-      "id": "partition-uuid",
-      "name": "urgent",
-      "queue": "emails",
+      "id": "7a30d768-7eb7-40dd-ade9-8afb20c18591",
+      "name": "Default",
+      "queue": "test-queue",
       "namespace": null,
       "task": null,
-      "priority": 10,
-      "options": { /* partition options */ },
-      "createdAt": "2025-10-08T05:13:37.541Z",
-      "depth": 10,
-      "processing": 2,
-      "total": 50
+      "queuePriority": 0,
+      "createdAt": "2025-10-15T06:21:42.865Z",
+      "depth": 2,
+      "processing": 0,
+      "total": 0
     }
   ]
 }
 ```
 
-#### 8.4 List Namespaces
-**Endpoint:** `GET /api/v1/resources/namespaces`
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
 
-Gets all namespaces with aggregated statistics.
+---
+
+### GET /api/v1/resources/namespaces
+
+**Purpose:** Get a list of all namespaces with statistics.
+
+**Authentication:** None
+
+**Query Parameters:** None
 
 **Response:**
 ```json
 {
   "namespaces": [
     {
-      "namespace": "production",
-      "queues": 5,
-      "partitions": 15,
+      "namespace": "benchmark",
+      "queues": 51,
+      "partitions": 510,
       "messages": {
-        "total": 1000,
-        "pending": 200
+        "total": 200000,
+        "pending": 0
       }
     }
   ]
 }
 ```
 
-#### 8.5 List Tasks
-**Endpoint:** `GET /api/v1/resources/tasks`
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
+---
+
+### GET /api/v1/resources/tasks
+
+**Purpose:** Get a list of all tasks with statistics.
 
-Gets all tasks with aggregated statistics.
+**Authentication:** None
+
+**Query Parameters:** None
 
 **Response:**
 ```json
 {
-  "tasks": [
-    {
-      "task": "notifications",
-      "queues": 3,
-      "partitions": 9,
-      "messages": {
-        "total": 500,
-        "pending": 100
-      }
-    }
-  ]
+  "tasks": []
 }
 ```
 
-#### 8.6 System Overview
-**Endpoint:** `GET /api/v1/resources/overview`
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
+---
+
+### GET /api/v1/resources/overview
 
-Gets a complete system overview with all key metrics.
+**Purpose:** Get a comprehensive system overview with all statistics.
+
+**Authentication:** None
+
+**Query Parameters:** None
 
 **Response:**
 ```json
 {
-  "queues": 8,
-  "partitions": 15,
-  "namespaces": 2,
-  "tasks": 3,
+  "queues": 53,
+  "partitions": 512,
+  "namespaces": 1,
+  "tasks": 0,
   "messages": {
-    "total": 1000,
-    "pending": 200,
-    "processing": 50,
-    "completed": 700,
-    "failed": 40,
-    "deadLetter": 10
+    "total": 200000,
+    "pending": 2,
+    "processing": 0,
+    "completed": 16493,
+    "failed": 0,
+    "deadLetter": 0
   },
-  "timestamp": "2025-10-08T07:29:35.682Z"
+  "timestamp": "2025-10-15T06:22:38.014Z"
 }
 ```
 
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
 ---
 
-## WebSocket Support
+## Status & Analytics
 
-### Dashboard WebSocket
-**Endpoint:** `ws://localhost:6632/ws/dashboard`
+### GET /api/v1/status
 
-Real-time updates for dashboard monitoring with V2 structure.
+**Purpose:** Get comprehensive dashboard status including throughput metrics and message statistics.
 
-#### Connection
-```javascript
-const ws = new WebSocket('ws://localhost:6632/ws/dashboard');
+**Authentication:** None
 
-ws.onopen = () => {
-  // Send ping to keep alive
-  setInterval(() => ws.send('ping'), 30000);
-  
-  // Optional: Subscribe to specific queues
-  ws.send(JSON.stringify({
-    type: 'subscribe',
-    queues: ['emails', 'payments']
-  }));
-};
-```
-
-#### Events (Server → Client)
+**Query Parameters:**
+- `from` (string, optional): Start date/time (ISO 8601)
+- `to` (string, optional): End date/time (ISO 8601)
+- `queue` (string, optional): Filter by queue name
+- `namespace` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
 
-**Connection Events:**
+**Response:**
 ```json
 {
-  "event": "connected",
-  "data": {
-    "connectionId": "uuid",
-    "version": "v2"
+  "timeRange": {
+    "from": "2025-10-15T05:22:39.466Z",
+    "to": "2025-10-15T06:22:39.466Z"
+  },
+  "throughput": [
+    {
+      "timestamp": "2025-10-15T06:22:00.000Z",
+      "ingested": 0,
+      "processed": 0,
+      "ingestedPerSecond": 0,
+      "processedPerSecond": 0
+    }
+  ],
+  "queues": [],
+  "messages": {
+    "total": 0,
+    "pending": 2,
+    "processing": 0,
+    "completed": 16493,
+    "failed": 0,
+    "deadLetter": 0
+  },
+  "leases": {
+    "active": 0,
+    "partitionsWithLeases": 0,
+    "totalBatchSize": 0,
+    "totalAcked": 0
   },
-  "timestamp": "2025-10-08T07:30:00.000Z"
+  "deadLetterQueue": {
+    "totalMessages": 0,
+    "affectedPartitions": 0,
+    "topErrors": []
+  }
 }
 ```
 
-**Message Events:**
-```json
-// Message pushed
-{
-  "event": "message.pushed",
-  "data": {
-    "queue": "emails",
-    "partition": "urgent",
-    "transactionId": "uuid"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
 
-// Message processing
-{
-  "event": "message.processing",
-  "data": {
-    "queue": "emails",
-    "partition": "urgent",
-    "transactionId": "uuid",
-    "workerId": "worker-123"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
+---
 
-// Message completed
-{
-  "event": "message.completed",
-  "data": {
-    "transactionId": "uuid"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
+### GET /api/v1/status/queues
 
-// Message failed
-{
-  "event": "message.failed",
-  "data": {
-    "transactionId": "uuid",
-    "error": "Processing error"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
-```
+**Purpose:** Get a list of queues with detailed status information.
 
-**Queue Events:**
+**Authentication:** None
+
+**Query Parameters:**
+- `from` (string, optional): Start date/time
+- `to` (string, optional): End date/time
+- `namespace` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
+- `limit` (number, optional): Number of results
+- `offset` (number, optional): Pagination offset
+
+**Response:**
 ```json
-// Queue created
 {
-  "event": "queue.created",
-  "data": {
-    "queue": "new-queue",
-    "partition": "Default"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
+  "queues": [
+    {
+      "id": "a6447f65-6c44-423e-a9b7-440fd7136d35",
+      "name": "__system_events__",
+      "namespace": null,
+      "task": null,
+      "priority": 100,
+      "createdAt": "2025-10-14T12:45:32.356Z",
+      "partitions": 1,
+      "messages": {
+        "total": 0,
+        "pending": 0,
+        "processing": 0,
+        "completed": 0,
+        "failed": 0,
+        "deadLetter": 0
+      },
+      "lag": null,
+      "performance": null
+    }
+  ]
 }
+```
+
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
+---
+
+### GET /api/v1/status/queues/:queue
+
+**Purpose:** Get detailed status information for a specific queue.
 
-// Queue depth update (every 5 seconds)
+**Authentication:** None
+
+**Path Parameters:**
+- `queue` (string): Queue name
+
+**Query Parameters:**
+- `from` (string, optional): Start date/time
+- `to` (string, optional): End date/time
+
+**Response:**
+```json
 {
-  "event": "queue.depth",
-  "data": {
-    "queue": "emails",
+  "queue": {
+    "id": "03093457-e6f6-4e5f-869b-045a6916fdff",
+    "name": "test-queue",
     "namespace": null,
     "task": null,
-    "totalDepth": 25,
-    "totalProcessing": 5,
-    "partitions": {
-      "Default": {
-        "depth": 10,
-        "processing": 2,
-        "completed": 100,
-        "failed": 5
+    "priority": 0,
+    "config": {
+      "leaseTime": 300,
+      "retryLimit": 3,
+      "ttl": 3600,
+      "maxQueueSize": 0
+    },
+    "createdAt": "2025-10-15T06:21:42.034Z"
+  },
+  "totals": {
+    "messages": {
+      "total": 0,
+      "pending": 0,
+      "processing": 0,
+      "completed": 3,
+      "failed": 0
+    },
+    "partitions": 1,
+    "consumed": 3,
+    "batches": 2
+  },
+  "partitions": [
+    {
+      "id": "7a30d768-7eb7-40dd-ade9-8afb20c18591",
+      "name": "Default",
+      "createdAt": "2025-10-15T06:21:42.865Z",
+      "lastActivity": "2025-10-15T06:22:21.725Z",
+      "messages": {
+        "total": 0,
+        "pending": 0,
+        "processing": 0,
+        "completed": 3,
+        "failed": 0
       },
-      "urgent": {
-        "depth": 15,
-        "processing": 3,
-        "completed": 50,
-        "failed": 2
+      "cursor": {
+        "totalConsumed": 3,
+        "batchesConsumed": 2,
+        "lastConsumedAt": "2025-10-15T06:22:10.537Z"
       }
     }
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
-
-// Partition depth update (every 5 seconds)
-{
-  "event": "partition.depth",
-  "data": {
-    "queue": "emails",
-    "partition": "urgent",
-    "depth": 15,
-    "processing": 3,
-    "completed": 50,
-    "failed": 2,
-    "total": 70
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
+  ],
+  "timeRange": {
+    "from": "2025-10-15T05:22:47.435Z",
+    "to": "2025-10-15T06:22:47.435Z"
+  }
 }
 ```
 
-**System Events:**
-```json
-// System statistics (every 10 seconds)
-{
-  "event": "system.stats",
-  "data": {
-    "pending": 200,
-    "processing": 50,
-    "recentCreated": 120,  // Last minute
-    "recentCompleted": 115, // Last minute
-    "connections": 5        // WebSocket connections
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
+**Status Codes:**
+- `200`: Success
+- `404`: Queue not found
+- `500`: Internal server error
 
-// Client connected
-{
-  "event": "client.connected",
-  "data": {
-    "clientId": "uuid"
-  },
-  "timestamp": "2025-10-08T07:30:00.000Z"
-}
+---
+
+### GET /api/v1/status/queues/:queue/messages
+
+**Purpose:** Get messages from a specific queue with filtering and pagination.
+
+**Authentication:** None
+
+**Path Parameters:**
+- `queue` (string): Queue name
 
-// Client disconnected
+**Query Parameters:**
+- `status` (string, optional): Filter by message status
+- `partition` (string, optional): Filter by partition
+- `from` (string, optional): Start date/time
+- `to` (string, optional): End date/time
+- `limit` (number, optional): Number of results
+- `offset` (number, optional): Pagination offset
+
+**Response:**
+```json
 {
-  "event": "client.disconnected",
-  "data": {
-    "clientId": "uuid"
+  "messages": [],
+  "pagination": {
+    "limit": 2,
+    "offset": null,
+    "total": 0
   },
-  "timestamp": "2025-10-08T07:30:00.000Z"
+  "queue": "test-queue",
+  "filters": {
+    "status": null,
+    "partition": null
+  },
+  "timeRange": {
+    "from": "2025-10-15T05:22:48.221Z",
+    "to": "2025-10-15T06:22:48.221Z"
+  }
 }
 ```
 
-#### Client → Server Messages
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
+
+---
 
-**Keep Alive:**
-```
-ping
-```
-Server responds with: `pong`
+### GET /api/v1/status/analytics
+
+**Purpose:** Get analytics data including time series metrics.
+
+**Authentication:** None
 
-**Subscribe to Queues:**
+**Query Parameters:**
+- `from` (string, optional): Start date/time
+- `to` (string, optional): End date/time
+- `queue` (string, optional): Filter by queue
+- `namespace` (string, optional): Filter by namespace
+- `task` (string, optional): Filter by task
+- `interval` (string, optional): Time interval: "minute", "hour", "day" (default: "hour")
+
+**Response:**
 ```json
 {
-  "type": "subscribe",
-  "queues": ["emails", "payments", "notifications"]
+  "timeRange": {
+    "from": "2025-10-15T05:22:50.000Z",
+    "to": "2025-10-15T06:22:50.000Z"
+  },
+  "interval": "hour",
+  "timeSeries": [],
+  "summary": null
 }
 ```
 
-**Note:** Subscription is optional and currently for future filtering implementation
+**Status Codes:**
+- `200`: Success
+- `500`: Internal server error
 
 ---
 
 ## Error Responses
 
-All endpoints may return error responses:
+All endpoints may return error responses in the following format:
 
 ```json
 {
@@ -1058,59 +1110,117 @@ All endpoints may return error responses:
 }
 ```
 
-**Common Status Codes:**
-- `200`: Success
-- `201`: Created
-- `204`: No Content (empty response)
-- `400`: Bad Request (invalid parameters)
-- `404`: Not Found
-- `500`: Internal Server Error
-- `503`: Service Unavailable (database connection issues)
+### Common Status Codes:
+
+- `200 OK`: Request successful
+- `201 Created`: Resource created successfully
+- `204 No Content`: Request successful but no content to return
+- `400 Bad Request`: Invalid request parameters or body
+- `404 Not Found`: Resource not found
+- `500 Internal Server Error`: Server error
+- `503 Service Unavailable`: Server is unhealthy or unavailable
 
 ---
 
-## Performance Considerations
+## WebSocket API
 
-1. **Batch Operations**: Use batch push/pop for better throughput
-2. **Long Polling**: Use `wait=true` to reduce polling overhead
-3. **Partition Strategy**: Use multiple partitions for parallel processing
-4. **Lease Time**: Set appropriate lease times based on processing duration
-5. **Connection Pooling**: System supports up to 10,000+ messages/second with proper configuration
+Queen also provides a WebSocket connection for real-time updates:
+
+**WebSocket URL:** `ws://localhost:6632/ws/dashboard`
+
+**Purpose:** Real-time updates for:
+- Queue depth changes
+- Message events (pushed, processing, completed, failed)
+- System statistics
 
 ---
 
-## Example Usage Flow
+## Notes
 
-```javascript
-// 1. Push a message
-POST /api/v1/push
-{
-  "items": [{
-    "queue": "orders",
-    "partition": "high-priority",
-    "payload": { "orderId": "12345", "amount": 99.99 }
-  }]
-}
+1. **CORS**: All endpoints support CORS with permissive settings. In production, configure appropriate CORS settings.
 
-// 2. Pop the message
-GET /api/v1/pop/queue/orders/partition/high-priority
+2. **Pagination**: Most list endpoints support pagination via `limit` and `offset` query parameters.
 
-// 3. Process the message...
+3. **Time Ranges**: Status and analytics endpoints default to the last 1 hour if no time range is specified.
 
-// 4. Acknowledge completion
-POST /api/v1/ack
-{
-  "transactionId": "returned-transaction-id",
-  "status": "completed"
-}
+4. **Consumer Groups**: Queen supports consumer groups for subscription-based message consumption, enabling multiple consumers to process messages in parallel without duplication.
+
+5. **Partitions**: Messages can be organized into partitions for better parallelism and ordering guarantees within partitions.
+
+6. **Namespaces and Tasks**: Optional organizational features for grouping queues logically.
+
+7. **Dead Letter Queue (DLQ)**: Failed messages can be moved to a DLQ for later analysis and reprocessing.
+
+8. **Encryption**: Encryption can be enabled by setting the `QUEEN_ENCRYPTION_KEY` environment variable.
+
+---
+
+## Examples
+
+### Creating a Queue and Sending Messages
+
+```bash
+# 1. Create a queue
+curl -X POST http://localhost:6632/api/v1/configure \
+  -H "Content-Type: application/json" \
+  -d '{
+    "queue": "my-queue",
+    "partition": "Default",
+    "ttl": 3600,
+    "priority": 1
+  }'
+
+# 2. Push messages
+curl -X POST http://localhost:6632/api/v1/push \
+  -H "Content-Type: application/json" \
+  -d '{
+    "items": [
+      {
+        "queue": "my-queue",
+        "partition": "Default",
+        "payload": {"task": "process-order", "orderId": 123}
+      }
+    ]
+  }'
+
+# 3. Pop messages
+curl "http://localhost:6632/api/v1/pop/queue/my-queue?batch=10"
+
+# 4. Acknowledge message
+curl -X POST http://localhost:6632/api/v1/ack \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transactionId": "<transaction-id-from-pop>",
+    "status": "completed"
+  }'
+```
+
+### Long Polling
+
+```bash
+# Wait up to 30 seconds for messages
+curl "http://localhost:6632/api/v1/pop/queue/my-queue?wait=true&timeout=30000&batch=10"
+```
+
+### Subscription Mode (Consumer Groups)
+
+```bash
+# Subscribe from earliest message
+curl "http://localhost:6632/api/v1/pop/queue/my-queue?consumerGroup=worker-group-1&subscriptionMode=earliest&batch=10"
+
+# Acknowledge for consumer group
+curl -X POST http://localhost:6632/api/v1/ack \
+  -H "Content-Type: application/json" \
+  -d '{
+    "transactionId": "<transaction-id>",
+    "status": "completed",
+    "consumerGroup": "worker-group-1"
+  }'
 ```
 
 ---
 
-## CORS Support
+**Last Updated:** October 15, 2025  
+**API Version:** v1  
+**Server Version:** Queen Message Queue
 
-All endpoints include CORS headers:
-- `Access-Control-Allow-Origin: *`
-- `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`
-- `Access-Control-Allow-Headers: Content-Type, Authorization`
-- `Access-Control-Max-Age: 86400`