info:
  name: Process Queue Item
  type: http
  seq: 7

http:
  method: POST
  url: '{{base_url}}/api/queue/items/{{queue_item_id}}/process'
  auth: inherit

docs: |-
  ## Process Queue Item

  Manually trigger processing of a specific queue item.

  **Method:** POST

  **Endpoint:** /api/queue/items/:queue_item_id/process

  **Authentication:** Required (Bearer token)

  **Path Parameters:**
  - `queue_item_id` (string): UUID of the queue item to process

  **Request Body:**
  Empty or optional:
  - `priority` (integer, optional): Override processing priority (0-10)
  - `force` (boolean, optional): Re-process even if completed

  **Response:**
  - `id` (string): Queue item UUID
  - `status` (string): New status - `processing` or `queued`
  - `type` (string): Item type
  - `message` (string): Processing initiation message
  - `estimated_duration_ms` (integer): Expected processing time
  - `started_at` (string): Processing start time
  - `previous_status` (string): Status before processing

  **Status Codes:**
  - 200: Processing started
  - 202: Queued for processing
  - 401: Unauthorized
  - 404: Queue item not found
  - 409: Item already being processed
  - 422: Invalid item state

  **Processing Behavior:**
  - Item moves from `pending` to `processing`
  - Can override priority for faster processing
  - Force re-processing of completed/failed items
  - Updates item's `last_attempt` timestamp
  - Increments `retry_count` for failed items
  - Validates data before processing
  - Executes item-specific handlers

  **Use Cases:**
  - Retry failed sync items
  - Expedite high-priority updates
  - Re-process completed items (e.g., after fix)
  - Debug queue processing
  - Manual intervention for stuck items
  - Test specific sync operations

  **Processing States:**
  - `pending` → `processing` → `completed` or `failed`
  - Processing can take 1-30 seconds depending on type
  - WebSocket notifications sent on completion
  - Automatic retry on transient failures

  **Notes:**
  - Does not guarantee immediate processing
  - Queue workers pick up items based on priority
  - Multiple manual processes queue sequentially
  - Use WebSocket for real-time updates