From de09dba28532af549b25dfdc35384a71aa1c223c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 1 Mar 2026 13:55:55 +0000 Subject: [PATCH] docs: update API and User Guide with search filters and saved searches - Document new /api/search endpoint with all filter parameters - Update saved searches docs with new allowed filter keys - Update User Guide with search view filters and saved searches usage Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> --- docs/API.md | 66 ++++++++++++++++++++++++++++++++++++++++++++--- docs/UserGuide.md | 25 +++++++++++++++--- 2 files changed, 85 insertions(+), 6 deletions(-) diff --git a/docs/API.md b/docs/API.md index 3613acfc..8cfc9e2d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -332,10 +332,62 @@ GET /api/files?status=completed&mime_type=application/pdf&tags=invoice&date_from > **Tip**: Filter state is reflected in query parameters, making URLs shareable as bookmarks or direct links. +### Full-Text Search + +**GET** `/api/search` + +Search documents by full text across OCR content, titles, filenames, tags, sender, and document type. Powered by Meilisearch. + +**Query Parameters**: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `q` | string | Yes | Full-text search query (1–512 chars) | +| `mime_type` | string | No | Filter by MIME type (e.g. `application/pdf`) | +| `document_type` | string | No | Filter by document type (e.g. `Invoice`) | +| `language` | string | No | Filter by language code (e.g. `de`, `en`) | +| `tags` | string | No | Filter by tag (exact match on a single tag) | +| `sender` | string | No | Filter by sender/absender (exact match) | +| `text_quality` | string | No | Filter by OCR text quality: `no_text`, `low`, `medium`, `high` | +| `date_from` | int | No | Filter results created after this Unix timestamp | +| `date_to` | int | No | Filter results created before this Unix timestamp | +| `page` | int | No | Page number, default: 1 | +| `per_page` | int | No | Results per page (1–100), default: 20 | + +**Example**: +``` +GET /api/search?q=invoice&document_type=Invoice&tags=amazon&text_quality=high&page=1 +``` + +**Response**: +```json +{ + "results": [ + { + "file_id": 42, + "original_filename": "2026-01-15_Invoice_Amazon.pdf", + "document_title": "Amazon Invoice January 2026", + "document_type": "Invoice", + "tags": ["amazon", "invoice"], + "_formatted": { + "document_title": "Amazon Invoice January 2026", + "ocr_text": "...total amount of the invoice is..." + } + } + ], + "total": 42, + "page": 1, + "pages": 3, + "query": "invoice" +} +``` + ### Saved Searches Saved searches allow users to save and reuse filter combinations. Each user can store up to 50 saved searches. +Saved searches are used on both the **Files** page (for file management filters) and the **Search** page (for content-finding filters including full-text queries). + #### List Saved Searches **GET** `/api/saved-searches` @@ -349,8 +401,9 @@ Returns all saved searches for the current user. "id": 1, "name": "Recent Invoices", "filters": { + "q": "invoice total", "tags": "invoice", - "status": "completed", + "document_type": "Invoice", "date_from": "2026-01-01" }, "created_at": "2026-03-01T10:00:00Z", @@ -368,14 +421,21 @@ Returns all saved searches for the current user. { "name": "Recent Invoices", "filters": { + "q": "invoice total", "tags": "invoice", - "status": "completed", + "document_type": "Invoice", "date_from": "2026-01-01" } } ``` -**Allowed filter keys**: `search`, `mime_type`, `status`, `date_from`, `date_to`, `storage_provider`, `tags`, `sort_by`, `sort_order` +**Allowed filter keys**: + +Files-view keys: `search`, `mime_type`, `status`, `storage_provider`, `sort_by`, `sort_order` + +Search-view keys: `q`, `document_type`, `language`, `sender`, `text_quality` + +Shared keys: `tags`, `date_from`, `date_to` **Response** (201 Created): The created saved search object. diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 57a4d56d..98ff365c 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -119,16 +119,35 @@ The **Files** page includes a full-text search bar (labelled "Full-Text Search") ### Dedicated Search Page -For a more focused search experience, use the **Search** page accessible from the main navigation: +For a more focused content-finding experience, use the **Search** page accessible from the main navigation: 1. Navigate to the **Search** page 2. Type your query into the search box — results appear automatically as you type (or press Enter) -3. Results are displayed in a Google-style format showing: +3. Use the **content-finding filters** to narrow results: + - **Document Type** — e.g. Invoice, Contract + - **Tags** — filter by a specific tag + - **Sender** — filter by sender / absender + - **Language** — filter by ISO language code (e.g. `de`, `en`) + - **Text Quality** — filter by OCR text quality (High, Medium, Low, No text) + - **Date From / Date To** — restrict results to a date range +4. Results are displayed in a Google-style format showing: - **Document title** (linked to the file detail page) - **Filename** - **Document type**, **sender**, and **tag** badges - **Content preview** with highlighted matching terms -4. Use pagination to browse through large result sets +5. Use pagination to browse through large result sets + +### Saved Searches + +Both the **Files** and **Search** pages support **saved searches** — named filter presets you can create and reuse: + +1. Apply your desired filters (and optionally a search query on the Search page) +2. Click **Save Current** in the saved searches bar +3. Enter a name for the saved search +4. Your saved search appears as a clickable tag — click it to instantly re-apply those filters +5. Click the **×** button next to a saved search to delete it + +On the **Search** page, saved searches store the full-text query (`q`) along with all active content-finding filters. On the **Files** page, saved searches store the file management filters (filename search, MIME type, status, etc.). The search page is also accessible via URL with a pre-filled query: `/search?q=invoice`