# Saved Filters API

## Overview

The Saved Filters API allows users to save and load custom filter presets for any resource type (media-items, collections, devices, etc.). Filters are user-specific and automatically scoped via JWT authentication.

**Base URL:** `/api/saved-filters`

**Authentication:** JWT token required (Bearer token)

---

## Endpoints

### GET /api/saved-filters

Retrieve all saved filters for the authenticated user and a specific resource type.

**Query Parameters:**
- `resource_type` (string, required) - Filter by resource type (e.g., "media-items", "collections")

**Response:** Array of saved filter objects

**Example Request:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \\
  "http://localhost:8765/api/saved-filters?resource_type=media-items"
```

**Example Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Sci-Fi Books",
    "resource_type": "media-items",
    "filters": {
      "genre_filter": "Science Fiction",
      "sort": "title ASC"
    },
    "created_at": "2024-03-20T12:00:00Z",
    "updated_at": "2024-03-20T12:00:00Z"
  }
]
```

---

### POST /api/saved-filters

Create a new saved filter for the authenticated user.

**Request Body:**
```json
{
  "name": "My Custom Filter",
  "resource_type": "media-items",
  "filters": {
    "search": "keyword",
    "author_filter": "Author Name",
    "genre_filter": "Genre",
    "sort": "title ASC"
  }
}
```

**Validation:**
- `name` (string, required, max 100 chars) - Must be unique per user + resource type
- `resource_type` (string, required) - Must be valid resource type
- `filters` (object, required) - Key-value pairs of filter criteria

**Response:** Created filter object (HTTP 201)

**Error Responses:**
- 409 Conflict - Filter name already exists for this user + resource type

---

### PUT /api/saved-filters/:id

Update an existing saved filter.

**URL Parameters:**
- `id` (UUID, required) - Filter ID to update

**Request Body:** Same as POST

**Response:** Updated filter object

**Error Responses:**
- 404 Not Found - Filter doesn't exist or doesn't belong to user
- 409 Conflict - New name conflicts with existing filter

---

### DELETE /api/saved-filters/:id

Delete a saved filter.

**URL Parameters:**
- `id` (UUID, required) - Filter ID to delete

**Response:** 204 No Content (success)

**Error Responses:**
- 404 Not Found - Filter doesn't exist or doesn't belong to user

### GET /api/saved-filters/:id

Retrieve a single saved filter by ID.

**URL Parameters:**
- `id` (UUID, required) - Filter ID to retrieve

**Response:** Single saved filter object (HTTP 200)

**Example Request:**
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \\
  "http://localhost:8765/api/saved-filters/550e8400-e29b-41d4-a716-446655440000"
```

**Example Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Sci-Fi Books",
  "resource_type": "media-items",
  "filters": {
    "genre_filter": "Science Fiction",
    "sort": "title ASC"
  },
  "created_at": "2024-03-20T12:00:00Z",
  "updated_at": "2024-03-20T12:00:00Z"
}
```

**Error Responses:**
- 400 Bad Request - Invalid filter ID format
- 401 Unauthorized - Invalid or missing authentication token
- 404 Not Found - Filter doesn't exist or doesn't belong to user

**Use Cases:**
- Mobile apps: Fetch filter details on-demand
- SPAs: Load filter data without page reload
- Editing: Pre-fill filter update form
- Verification: Check filter exists before operations

---
