info:
  name: Clear Failed Items
  type: http
  seq: 8

http:
  method: DELETE
  url: '{{base_url}}/api/queue/clear-failed'
  auth: inherit

docs: |-
  ## Clear Failed Queue Items

  Removes all failed queue items from the queue.

  **Method:** DELETE

  **Endpoint:** /api/queue/clear-failed

  **Authentication:** Required (Bearer token)

  **Query Parameters:**
  - `older_than` (string, optional): ISO 8601 duration - e.g., `7d`, `24h`, `60m`
  - `device_id` (string, optional): Only clear items from specific device
  - `type` (string, optional): Only clear specific item type

  **Request Body:**
  Optional filters:
  ```json
  {
    "older_than": "7d",
    "device_id": "uuid",
    "type": "progress"
  }
  ```

  **Response:**
  - `deleted_count` (integer): Number of items deleted
  - `items_cleared` (array): IDs of cleared items
  - `retained_count` (integer): Items not matching filters
  - `cleared_at` (string): Deletion timestamp

  **Status Codes:**
  - 200: Items cleared successfully
  - 401: Unauthorized
  - 400: Invalid filter parameters

  **Deletion Behavior:**
  - Removes failed items from queue
  - Does not affect pending/processing/completed items
  - Permanent deletion (cannot be undone)
  - Logs deletion for audit trail
  - Updates queue statistics

  **Safety Features:**
  - Default filter prevents clearing recent failures
  - Per-device filtering for targeted cleanup
  - Type filtering for selective clearing
  - Confirmation required for large deletions

  **Recommended Usage:**
  - **Daily:** Clear failures older than 7 days
  - **Weekly:** Clear all failed items
  - **Per-device:** After removing problematic device
  - **Per-type:** After fixing specific sync issue

  **Use Cases:**
  - Clean up old failed sync attempts
  - Reduce queue database size
  - Remove stuck error items
  - Prepare for fresh sync attempts
  - Clear items for decommissioned devices
  - Reset after bug fixes

  **Warnings:**
  - Cannot be undone
  - Failed items cleared permanently
  - Consider retrying before clearing
  - May hide recurring issues if overused
  - Check logs before bulk clearing

  **Best Practices:**
  - Review error patterns before clearing
  - Fix root causes before cleanup
  - Use time-based filters to preserve recent failures
  - Document reasons for clearing
  - Monitor failure rates after cleanup