### Set up development environment from source

Source: https://github.com/zen-logic/file-hunter/blob/main/CONTRIBUTING.md

Set up a development environment from source: clone the repository, create and activate a virtual environment, install dependencies, and start the server.

```bash
git clone https://github.com/zen-logic/file-hunter.git
cd file-hunter
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m file_hunter
```

--------------------------------

### Run File Hunter from release archive

Source: https://github.com/zen-logic/file-hunter/blob/main/CONTRIBUTING.md

Run the bundled launcher from a release archive. It creates a virtual environment, installs dependencies, and starts the server; the first run prompts for basic configuration.

```bash
./filehunter
```

--------------------------------

### POST /api/auth/setup

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Performs first-time setup of the server. No authentication required. Only works on first-time setup.

```APIDOC
## POST /api/auth/setup

### Description
Performs first-time setup of the server. No authentication required. Only works on first-time setup.

### Method
POST

### Endpoint
/api/auth/setup

### Parameters
#### Request Body
- **username** (string) - Required - The username for the admin account.
- **password** (string) - Required - The password for the admin account.
- **displayName** (string) - Required - The display name for the admin account.

### Request Example
{"username": "admin", "password": "secret", "displayName": "Admin"}

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **user** (object) - The created user object.
  - **id** (integer) - User ID.
  - **username** (string) - Username.
  - **displayName** (string) - Display name.

#### Response Example
{"token": "abc123...", "user": {"id": 1, "username": "admin", "displayName": "Admin"}}
```

--------------------------------

### GET /api/auth/status

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the authentication status and whether the server needs initial setup. No authentication required.

```APIDOC
## GET /api/auth/status

### Description
Returns the authentication status and whether the server needs initial setup. No authentication required.

### Method
GET

### Endpoint
/api/auth/status

### Response
#### Success Response (200)
- **needsSetup** (boolean) - Whether the server needs initial setup.
- **serverName** (string) - The server name.

#### Response Example
{"needsSetup": false, "serverName": "My Server"}
```

--------------------------------

### GET /api/browse?path=/mnt

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Browses the local agent's filesystem for location setup.

```APIDOC
## GET /api/browse?path=/mnt

### Description
Browses the local agent's filesystem for location setup.

### Method
GET

### Endpoint
/api/browse

### Parameters
#### Query Parameters
- **path** (string) - Required - The filesystem path to browse.

### Request Example
(No explicit request example provided)

### Response
#### Success Response (200)
- **path** (string) - The path that was browsed.
- **entries** (array) - List of entries, each with **name** (string) and **type** (string, e.g., "directory").

#### Response Example
{
  "path": "/mnt",
  "entries": [
    {"name": "photos", "type": "directory"}
  ]
}
```

--------------------------------

### Install File Hunter from source

Source: https://github.com/zen-logic/file-hunter/blob/main/README.md

Install File Hunter from source. Clones the main repository and the agent repository, then runs the launcher from the file-hunter directory.

```bash
git clone https://github.com/zen-logic/file-hunter.git
git clone https://github.com/zen-logic/file-hunter-agent.git
cd file-hunter
./filehunter
```

--------------------------------

### POST /api/scan/quick - Start quick scan

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts a quick scan. Requires agent support.

```json
// Request
{"location_id": "loc-1", "folder_id": "fld-10"}

// Response
{"message": "Quick scan started"}
```

--------------------------------

### Install File Hunter with curl

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/index.html

One-line installer for File Hunter. Downloads and runs the install script from the official site. Use this on any system with curl and bash, including headless servers.

```bash
curl -fsSL https://filehunter.zenlogic.uk/install | bash
```

--------------------------------

### Run File Hunter

Source: https://github.com/zen-logic/file-hunter/blob/main/README.md

Run File Hunter after installation. On first run, the launcher prompts for host and port, creates a virtual environment, and installs dependencies. Then open the URL shown in your browser.

```bash
cd filehunter-x.x.x
./filehunter
```

--------------------------------

### POST /api/folders/{id}/download - Start async ZIP build

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts an asynchronous ZIP build for a folder. The response includes a jobId and the total number of items.

```json
{"jobId": "abc-123", "total": 50}
```

--------------------------------

### GET /api/version - Get version

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the current server version and whether the Pro edition is active.

```json
{"version": "1.3.5", "pro": false}
```

--------------------------------

### GET /api/tags/{tags} - Find files by tags (AND)

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Finds files matching all specified tags. Tags are comma-separated in the URL path and normalized (case-insensitive, whitespace-trimmed). The example shows a request for tags 'people,outdoors,sunny' and a response with a matching file.

```http
GET /api/tags/people,outdoors,sunny
```

```json
[
  {
    "id": 123,
    "name": "beach.jpg",
    "path": "holiday/beach.jpg",
    "typeHigh": "image",
    "typeLow": "jpg",
    "size": 4567890,
    "date": "2024-06-15T10:30:00",
    "locationId": 1,
    "location": "Photos"
  }
]
```

--------------------------------

### GET /api/settings - Get settings

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the current server settings, including server name and hidden file visibility. The ellipsis indicates additional fields.

```json
{"serverName": "My Server", "showHiddenFiles": "0", ...}
```

--------------------------------

### POST /api/auth/setup request and response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

First-time setup request and response for POST /api/auth/setup. No auth required.

```json
// Request
{"username": "admin", "password": "secret", "displayName": "Admin"}

// Response
{"token": "abc123...", "user": {"id": 1, "username": "admin", "displayName": "Admin"}}
```

--------------------------------

### POST /api/batch/download

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts an asynchronous ZIP build for selected items.

```APIDOC
## POST /api/batch/download

### Description
Starts an asynchronous ZIP build for selected items.

### Method
POST

### Endpoint
/api/batch/download

### Parameters
#### Request Body
- **file_ids** (array of numbers) - Optional - IDs of files to include in the ZIP.
- **folder_ids** (array of numbers) - Optional - IDs of folders to include in the ZIP.

### Request Example
```json
{"file_ids": [1, 2], "folder_ids": [10]}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the ZIP build job.
- **total** (number) - The total number of items included.

#### Response Example
```json
{"jobId": "abc-123", "total": 25}
```
```

--------------------------------

### POST /api/scan/quick

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Start a quick scan (requires agent support).

```APIDOC
## POST /api/scan/quick

### Description
Start a quick scan (requires agent support).

### Method
POST

### Endpoint
/api/scan/quick

### Parameters
#### Request Body
- **location_id** (string) - Required - The ID of the location to scan.
- **folder_id** (string) - Optional - The ID of a specific folder to scan.

### Request Example
{
  "location_id": "loc-1",
  "folder_id": "fld-10"
}

### Response
#### Success Response (200)
- **message** (string) - A message indicating the quick scan started.

#### Response Example
{
  "message": "Quick scan started"
}
```

--------------------------------

### GET /api/tags - Retrieve full tag vocabulary

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the complete list of tags as a JSON array. Example response shows tags like 'beach', 'holiday', and 'work'.

```json
["beach", "holiday", "work"]
```

--------------------------------

### POST /api/folders/{id}/download

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts an asynchronous ZIP build for a folder.

```APIDOC
## POST /api/folders/{id}/download

### Description
Starts an asynchronous ZIP build for a folder.

### Method
POST

### Endpoint
/api/folders/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - Folder ID.

### Response
#### Success Response (200)
- **jobId** (string) - Job identifier for the async operation.
- **total** (number) - Total number of items to process.

#### Response Example
```json
{"jobId": "abc-123", "total": 50}
```
```

--------------------------------

### GET /api/settings

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the current server settings.

```APIDOC
## GET /api/settings

### Description
Returns the current server settings.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **serverName** (string) - Server name
- **showHiddenFiles** (string) - Whether hidden files are shown
- Additional settings fields

#### Response Example
```json
{"serverName": "My Server", "showHiddenFiles": "0", ...}
```
```

--------------------------------

### POST /api/batch/consolidate - Request and Response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts batch consolidation in the background. The request includes file IDs, consolidation mode, destination folder, and filename matching option. The response confirms the batch consolidation started.

```json
// Request
{
  "file_ids": [123, 456],
  "mode": "keep_here",
  "consolidateMode": "move",
  "destination_folder_id": "fld-10",
  "filename_match_only": false
}

// Response
{"message": "Batch consolidation started for 2 files"}
```

--------------------------------

### POST /api/update/install

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Installs an update using a license key.

```APIDOC
## POST /api/update/install

### Description
Installs an update using a license key.

### Method
POST

### Endpoint
/api/update/install

### Parameters
#### Request Body
- **key** (string) - Required - License key for authentication.

### Request Example
{"key": "license-key"}

### Response
#### Success Response (200)
- Response contains install result (not specified).
```

--------------------------------

### POST /api/scan - Start full scan

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts a full scan. The folder_id field is optional. The response includes a queue ID.

```json
// Request
{"location_id": "loc-1", "folder_id": "fld-10"}  // folder_id optional

// Response
{"message": "Scan queued for 'Photos / Subfolder'", "queue_id": 42}
```

--------------------------------

### GET /api/auth/me response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/auth/me.

```json
{"id": 1, "username": "admin", "displayName": "Admin"}
```

--------------------------------

### POST /api/consolidate - Request and Response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts a single-file consolidation (move or copy duplicates). The mode and consolidateMode fields control the operation; destination_folder_id is required for move_to and copy modes. The response confirms the consolidation started for the file.

```json
// Request
{
  "file_id": 123,
  "mode": "keep_here",          // keep_here|move_to
  "consolidateMode": "move",    // move|copy
  "destination_folder_id": "fld-10",  // required for move_to and copy
  "filename_match_only": false,
  "stub_file_ids": [456, 789]   // optional: specific copies to process
}

// Response
{"message": "Consolidation started for 'photo.jpg'"}
```

--------------------------------

### POST /api/scan

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Start a full scan.

```APIDOC
## POST /api/scan

### Description
Start a full scan.

### Method
POST

### Endpoint
/api/scan

### Parameters
#### Request Body
- **location_id** (string) - Required - The ID of the location to scan.
- **folder_id** (string) - Optional - The ID of a specific folder to scan.

### Request Example
{
  "location_id": "loc-1",
  "folder_id": "fld-10"
}

### Response
#### Success Response (200)
- **message** (string) - A message indicating the scan was queued.
- **queue_id** (integer) - The ID of the queued scan.

#### Response Example
{
  "message": "Scan queued for 'Photos / Subfolder'",
  "queue_id": 42
}
```

--------------------------------

### GET /api/scan/capabilities - Get scan capabilities

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns scan capabilities for a location. The response indicates whether quick scan is supported.

```json
{"quick_scan": true}
```

--------------------------------

### POST /api/update/apply-release

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Downloads and installs the latest version from GitHub, then restarts the application.

```APIDOC
## POST /api/update/apply-release

### Description
Downloads and installs the latest version from GitHub, then restarts the application.

### Method
POST

### Endpoint
/api/update/apply-release

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{"message": "Updated to v1.3.6. Restarting..."}
```

--------------------------------

### GET /api/themes

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Lists available themes.

```APIDOC
## GET /api/themes

### Description
Lists available themes.

### Method
GET

### Endpoint
/api/themes

### Response
#### Success Response (200)
- **name** (string) - Theme name
- **builtIn** (boolean) - Whether the theme is built-in

#### Response Example
```json
[{"name": "default", "builtIn": true}, {"name": "dark-blue", "builtIn": false}]
```
```

--------------------------------

### GET /api/version

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the server version and whether Pro is enabled.

```APIDOC
## GET /api/version

### Description
Returns the server version and whether Pro is enabled.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **version** (string) - Server version
- **pro** (boolean) - Whether Pro is enabled

#### Response Example
```json
{"version": "1.3.5", "pro": false}
```
```

--------------------------------

### GET /api/folders/{id}/stats - Get folder statistics

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns statistics for a folder, including file count and total size.

```json
{"file_count": 100, "total_size": 12345678, ...}
```

--------------------------------

### GET /api/pro/status - Get Pro status

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the Pro status. When active, includes enabled features and version; otherwise returns an empty features array.

```json
{"active": true, "features": ["webdav", "agents"], "version": "1.0.0"}
// or
{"active": false, "features": []}
```

--------------------------------

### POST /api/consolidate

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts a single-file consolidation (move or copy duplicates).

```APIDOC
## POST /api/consolidate

### Description
Starts a single-file consolidation (move or copy duplicates).

### Method
POST

### Endpoint
/api/consolidate

### Parameters
#### Request Body
- **file_id** (number) - Required - The ID of the file to consolidate.
- **mode** (string) - Required - `keep_here` or `move_to`.
- **consolidateMode** (string) - Required - `move` or `copy`.
- **destination_folder_id** (string) - Required for `move_to` and `copy` - The destination folder ID.
- **filename_match_only** (boolean) - Optional - If true, only consider duplicates with matching filenames.
- **stub_file_ids** (array of numbers) - Optional - Specific copies to process.

### Request Example
```json
{
  "file_id": 123,
  "mode": "keep_here",
  "consolidateMode": "move",
  "destination_folder_id": "fld-10",
  "filename_match_only": false,
  "stub_file_ids": [456, 789]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{"message": "Consolidation started for 'photo.jpg'"}
```
```

--------------------------------

### GET /api/files/{id}

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Full file detail.

```APIDOC
## GET /api/files/{id}

### Description
Full file detail.

### Method
GET

### Endpoint
/api/files/{id}

### Parameters
#### Path Parameters
- **id** (number) - Required - File ID.

### Response
#### Success Response (200)
- **id** (number) - File ID.
- **name** (string) - File name.
- **folderId** (string) - Folder ID.
- **locationId** (string) - Location ID.
- **locationOnline** (boolean) - Whether location is online.
- **locationName** (string) - Location name.
- **path** (string) - Full path.
- **online** (boolean) - Whether file is online.
- **typeHigh** (string) - High-level type.
- **typeLow** (string) - Low-level type.
- **size** (number) - File size.
- **date** (string) - File date.
- **created** (string) - Creation date.
- **cataloged** (string) - Cataloged date.
- **lastSeen** (string) - Last seen date.
- **hashPartial** (string) - Partial hash.
- **hashFast** (string) - Fast hash.
- **hashStrong** (string) - Strong hash.
- **verified** (boolean) - Verified flag.
- **stale** (boolean) - Stale flag.
- **pendingOp** (string) - Pending operation.
- **description** (string) - Description.
- **tags** (array) - Tags.
- **duplicates** (array) - Duplicate file info.
- **dupTotal** (number) - Total duplicates.
- **breadcrumb** (array) - Breadcrumb trail.
- **canTranscode** (boolean) - Whether transcode is possible.
- **transcodeStatus** (string) - Transcode status.

#### Response Example
```json
{
  "id": 123,
  "name": "photo.jpg",
  "folderId": "fld-5",
  "locationId": "loc-1",
  "locationOnline": true,
  "locationName": "Photos",
  "path": "/Photos/2024/photo.jpg",
  "online": true,
  "typeHigh": "image",
  "typeLow": "jpg",
  "size": 4567890,
  "date": "2024-06-15T10:30:00",
  "created": "2024-06-15T10:30:00",
  "cataloged": "2024-07-01T12:00:00",
  "lastSeen": "2024-08-20T09:00:00",
  "hashPartial": "abc123...",
  "hashFast": "a1b2c3d4e5f67890",
  "hashStrong": null,
  "verified": false,
  "stale": false,
  "pendingOp": null,
  "description": "",
  "tags": ["holiday", "beach"],
  "duplicates": [
    {"fileId": 456, "name": "photo.jpg", "location": "Backup", "agent": "Remote", "locationId": 2, "path": "/backup/photo.jpg"}
  ],
  "dupTotal": 1,
  "breadcrumb": [
    {"nodeId": "loc-1", "name": "Photos"},
    {"nodeId": "fld-5", "name": "2024"}
  ],
  "canTranscode": false,
  "transcodeStatus": null
}
```
```

--------------------------------

### GET /api/files

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

List files with filtering, sorting, and pagination.

```APIDOC
## GET /api/files

### Description
List files with filtering, sorting, and pagination.

### Method
GET

### Endpoint
/api/files

### Parameters
#### Query Parameters
- **folder_id** (string) - Required - Location or folder ID.
- **page** (number) - Optional - Page number (default 0).
- **sort** (string) - Optional - Sort field: name|type|size|date|dups.
- **sortDir** (string) - Optional - Sort direction: asc|desc.
- **filter** (string) - Optional - Filter string.
- **focusFile** (string) - Optional - File ID to focus.
- **fresh** (boolean) - Optional - Skip freshness check.

### Response
#### Success Response (200)
- **items** (array) - Array of file items.
- **folders** (array) - Array of subfolder summaries.
- **total** (number) - Total number of files.
- **page** (number) - Current page.
- **pageSize** (number) - Page size.
- **breadcrumb** (array) - Breadcrumb trail.

#### Response Example
```json
{
  "items": [
    {
      "id": 123, "name": "photo.jpg", "rel_path": "2024/photo.jpg",
      "typeHigh": "image", "typeLow": "jpg", "size": 4567890,
      "date": "2024-06-15T10:30:00", "stale": false, "hidden": false,
      "hashFast": "a1b2c3d4e5f67890", "hashStrong": null,
      "dupCount": 2, "pendingOp": null
    }
  ],
  "folders": [
    {"id": "fld-10", "name": "Subfolder", "file_count": 50, "has_children": true}
  ],
  "total": 500,
  "page": 0,
  "pageSize": 120,
  "breadcrumb": [
    {"nodeId": "loc-1", "name": "Photos"},
    {"nodeId": "fld-5", "name": "2024"}
  ]
}
```
```

--------------------------------

### POST /api/stats/repair

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts a catalog repair operation with selectable phases.

```APIDOC
## POST /api/stats/repair

### Description
Starts a catalog repair operation with selectable phases. If no phases are provided, all phases are run.

### Method
POST

### Endpoint
/api/stats/repair

### Parameters
#### Request Body
- **phases** (array of strings) - Optional - List of phases to run. Possible values: "partials", "hashes", "duplicates", "sizes". Defaults to all phases if omitted.

### Request Example
{"phases": ["partials", "hashes", "duplicates", "sizes"]}

### Response
#### Success Response (200)
- **status** (string) - Status of the repair operation, e.g., "started".
- **phases** (array of strings) - List of phases that will be run.

#### Response Example
{"status": "started", "phases": ["partials", "hashes", "duplicates", "sizes"]}
```

--------------------------------

### GET /api/favourites

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

List all favourites.

```APIDOC
## GET /api/favourites

### Description
List all favourites.

### Method
GET

### Endpoint
/api/favourites

### Response
#### Success Response (200)
- **response** (array) - Array of favourite items.

#### Response Example
```json
[
  {"id": "loc-1", "name": "Photos", "type": "location", "path": "Photos", "locationId": "loc-1"},
  {"id": "fld-42", "name": "2024", "type": "folder", "path": "Local Agent / Photos / 2024", "locationId": "loc-1"}
]
```
```

--------------------------------

### GET /api/auth/apps

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Lists all registered API applications (tokens).

```APIDOC
## GET /api/auth/apps

### Description
Lists all registered API applications (tokens).

### Method
GET

### Endpoint
/api/auth/apps

### Response
#### Success Response (200)
- **id** (number) - Application ID
- **name** (string) - Application name
- **token** (string) - API token
- **created_at** (string) - Creation timestamp

#### Response Example
```json
[{"id": 1, "name": "My App", "token": "tok_...", "created_at": "2025-01-01T00:00:00"}]
```
```

--------------------------------

### GET /api/browse/

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the root of the hierarchical catalog discovery.

```APIDOC
## GET /api/browse/

### Description
Returns the root of the hierarchical catalog discovery.

### Method
GET

### Endpoint
/api/browse/

### Parameters
None

### Request Example
(No explicit request example provided)

### Response
#### Success Response (200)
- **kind** (string) - Always "root".
- **children** (array) - List of child nodes, each with **kind** (string) and **name** (string).

#### Response Example
{
  "kind": "root",
  "children": [
    {"kind": "agent", "name": "Local Agent"}
  ]
}
```

--------------------------------

### GET /api/themes - List themes

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns a list of available themes, indicating whether each is built-in or user-defined.

```json
[{"name": "default", "builtIn": true}, {"name": "dark-blue", "builtIn": false}]
```

--------------------------------

### GET /api/tree/expand

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Ancestor chain + children at each level for a target folder.

```APIDOC
## GET /api/tree/expand

### Description
Ancestor chain + children at each level for a target folder.

### Method
GET

### Endpoint
/api/tree/expand?target=42

### Parameters
#### Query Parameters
- **target** (number) - Required - Target folder ID.

### Response
#### Success Response (200)
- **ancestors** (array) - Ancestor chain.
- **children** (object) - Children at each level.

#### Response Example
```json
{"ancestors": [...], "children": {...}}
```
```

--------------------------------

### GET /api/ignore response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

JSON array of ignore rules, each with id, filename, file_size, location_id, and created_at.

```json
[{"id": 1, "filename": "Thumbs.db", "file_size": 0, "location_id": null, "created_at": "..."}]
```

--------------------------------

### GET /api/stats response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/stats. Shows total file count, total size, number of locations and agents, and a type breakdown with example values.

```json
{
  "total_files": 16000000, "total_size": 12345678901234,
  "locations": 20, "agents": 6,
  "type_breakdown": {"image": 8000000, "video": 2000000, ...},
  ...
}
```

--------------------------------

### GET /api/zip/{job_id}/download

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Streams the built ZIP file for a given job ID.

```APIDOC
## GET /api/zip/{job_id}/download

### Description
Streams the built ZIP file. Returns `application/zip` with `Content-Disposition` and `Content-Length` headers.

### Method
GET

### Endpoint
/api/zip/{job_id}/download

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the ZIP build job.

### Response
#### Success Response (200)
- **Content-Type** (string) - `application/zip`
- **Content-Disposition** (string) - Attachment header with filename.
- **Content-Length** (number) - Size of the ZIP file.
```

--------------------------------

### Run File Hunter with demo data

Source: https://github.com/zen-logic/file-hunter/blob/main/CONTRIBUTING.md

Start the server with sample data populated on first run. Use this after setting up the development environment.

```bash
python -m file_hunter --demo
```

--------------------------------

### GET /api/dup-exclude/progress - Check duplicate exclusion progress

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the progress of a duplicate exclusion operation. The example shows a running status with processed and total counts.

```json
{"status": "running", "processed": 100, "total": 500, ...}
```

--------------------------------

### GET /api/browse/ response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

JSON response for the catalog root, listing agent children.

```json
{"kind": "root", "children": [{"kind": "agent", "name": "Local Agent"}]}
```

--------------------------------

### GET /api/tree/children

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Batch fetch immediate children for folder IDs (comma-separated).

```APIDOC
## GET /api/tree/children

### Description
Batch fetch immediate children for folder IDs (comma-separated).

### Method
GET

### Endpoint
/api/tree/children?ids=1,2,3

### Parameters
#### Query Parameters
- **ids** (string) - Required - Comma-separated folder IDs.

### Response
#### Success Response (200)
- **response** (object) - Map of folder ID to array of child items.

#### Response Example
```json
{"1": [{"id": "fld-10", "name": "Sub", ...}], "2": [...]}
```
```

--------------------------------

### POST /api/folders/{id}/dup-exclude - Toggle duplicate exclusion

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Toggles duplicate exclusion on a folder tree. The first call returns counts for confirmation; the second call with 'confirmed: true' starts the operation. The example shows both the confirmation and execution requests and responses.

```json
// Request (confirmation)
{"exclude": true}
// Response
{"confirm": true, "folderName": "Archive", "folderCount": 10, "fileCount": 500, "direction": "exclude"}

// Request (execute)
{"exclude": true, "confirmed": true}
// Response
{"started": true}
```

--------------------------------

### GET /api/scan/queue

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Get the current scan queue.

```APIDOC
## GET /api/scan/queue

### Description
Get the current scan queue.

### Method
GET

### Endpoint
/api/scan/queue

### Response
#### Success Response (200)
- **queue_id** (integer) - The ID of the queued operation.
- **type** (string) - The type of operation (e.g., `scan_dir`).
- **location_id** (integer) - The ID of the location.
- **name** (string) - The name of the item being scanned.
- **status** (string) - The status of the operation (e.g., `running`).

#### Response Example
[
  {
    "queue_id": 42,
    "type": "scan_dir",
    "location_id": 1,
    "name": "Photos",
    "status": "running"
  }
]
```

--------------------------------

### Lint and format with Ruff

Source: https://github.com/zen-logic/file-hunter/blob/main/CONTRIBUTING.md

Install Ruff and run linting and formatting checks. Both commands should be run before submitting a pull request.

```bash
pip install ruff
ruff check .
ruff format .
```

--------------------------------

### GET /api/scan/capabilities

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Get scan capabilities for a location.

```APIDOC
## GET /api/scan/capabilities

### Description
Get scan capabilities for a location.

### Method
GET

### Endpoint
/api/scan/capabilities

### Parameters
#### Query Parameters
- **location_id** (string) - Required - The ID of the location.

### Response
#### Success Response (200)
- **quick_scan** (boolean) - Whether quick scan is supported.

#### Response Example
{
  "quick_scan": true
}
```

--------------------------------

### GET /api/auth/users response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/auth/users.

```json
[{"id": 1, "username": "admin", "displayName": "Admin"}, ...]
```

--------------------------------

### POST /api/update/install request and response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Request and response for POST /api/update/install. The request includes a license key; the response contains the install result.

```json
// Request
{"key": "license-key"}

// Response — install result
```

--------------------------------

### GET /api/files/{id}/base64

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Get file content as base64.

```APIDOC
## GET /api/files/{id}/base64

### Description
Get file content as base64.

### Method
GET

### Endpoint
/api/files/{id}/base64

### Parameters
#### Path Parameters
- **id** (number) - Required - File ID.

### Response
#### Success Response (200)
- **media_type** (string) - Media type.
- **data** (string) - Base64 data.

#### Response Example
```json
{"media_type": "image/jpeg", "data": "/9j/4AAQ..."}
```
```

--------------------------------

### POST /api/batch/download - Request and Response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts an asynchronous ZIP build for selected items. The response contains a job ID and total count.

```json
// Request
{"file_ids": [1, 2], "folder_ids": [10]}

// Response
{"jobId": "abc-123", "total": 25}
```

--------------------------------

### GET /api/auth/status response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/auth/status. No auth required.

```json
{"needsSetup": false, "serverName": "My Server"}
```

--------------------------------

### GET /api/slideshow-ids response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response body for GET /api/slideshow-ids. Returns an array of ids and the total count.

```json
{"ids": [1, 2, 3, 4, 5], "total": 5}
```

--------------------------------

### GET /api/locations/{id}/stats

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Gets statistics for a specific location, including file count and size.

```APIDOC
## GET /api/locations/{id}/stats

### Description
Retrieves statistics for a specific location.

### Method
GET

### Endpoint
/api/locations/{id}/stats

### Path Parameters
- **id** (string) - Required - Location ID

### Response
#### Success Response (200)
- **file_count** (number) - Number of files
- **total_size** (number) - Total size in bytes
- **type_breakdown** (object) - Breakdown by file type

#### Response Example
```json
{"file_count": 1234, "total_size": 5678901234, "type_breakdown": {}}
```
```

--------------------------------

### POST /api/locations/{id}/download

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Initiates an asynchronous ZIP build of the entire location.

```APIDOC
## POST /api/locations/{id}/download

### Description
Starts an asynchronous ZIP build of the entire location.

### Method
POST

### Endpoint
/api/locations/{id}/download

### Path Parameters
- **id** (string) - Required - Location ID

### Response
#### Success Response (200)
- **jobId** (string) - Job identifier for the async build
- **total** (number) - Total number of items

#### Response Example
```json
{"jobId": "abc-123", "total": 1234}
```
```

--------------------------------

### GET /api/update/check-release response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/update/check-release. Shows the current and latest versions, whether an update is available, and the download URL.

```json
{"current": "1.3.5", "latest": "1.3.6", "update_available": true, "download_url": "..."}
```

--------------------------------

### POST /api/auth/apps

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Creates a new API application and returns its token.

```APIDOC
## POST /api/auth/apps

### Description
Creates a new API application and returns its token.

### Method
POST

### Endpoint
/api/auth/apps

### Parameters
#### Request Body
- **name** (string) - Required - Application name

### Request Example
```json
{"name": "My App"}
```

### Response
#### Success Response (200)
- **id** (number) - Application ID
- **name** (string) - Application name
- **token** (string) - API token

#### Response Example
```json
{"id": 1, "name": "My App", "token": "tok_..."}
```
```

--------------------------------

### GET /api/searches response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response body for GET /api/searches. Returns a list of saved searches with id, name, params, and created_at.

```json
[{"id": 1, "name": "Holiday photos", "params": "{...}", "created_at": "2025-01-01T00:00:00"}]
```

--------------------------------

### GET /api/locations/{id}/stats response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/locations/{id}/stats. Contains file count, total size, and a type breakdown.

```json
{"file_count": 1234, "total_size": 5678901234, "type_breakdown": {...}, ...}
```

--------------------------------

### POST /api/consolidate/preview

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Preview duplicate counts and locations for a set of files.

```APIDOC
## POST /api/consolidate/preview

### Description
Preview duplicate counts and locations for a set of files.

### Method
POST

### Endpoint
/api/consolidate/preview

### Parameters
#### Request Body
- **file_ids** (array of numbers) - Required - IDs of files to preview duplicates for.

### Request Example
```json
{"file_ids": [123, 456]}
```

### Response
#### Success Response (200)
- **total_dups** (number) - Total number of duplicates found.
- **filename_matched_dups** (number) - Number of duplicates with matching filenames.
- **duplicates** (array) - List of duplicate file details.
  - **fileId** (number) - ID of the duplicate file.
  - **name** (string) - Name of the duplicate file.
  - **location** (string) - Location name.
  - **agent** (string) - Agent type (e.g., Remote).
  - **locationId** (number) - ID of the location.
  - **path** (string) - Full path of the duplicate file.

#### Response Example
```json
{
  "total_dups": 5,
  "filename_matched_dups": 3,
  "duplicates": [
    {"fileId": 789, "name": "photo.jpg", "location": "Backup", "agent": "Remote", "locationId": 2, "path": "/backup/photo.jpg"}
  ]
}
```
```

--------------------------------

### GET /api/scan/queue - Get scan queue

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns the current scan queue. Each entry includes queue ID, type, location ID, name, and status.

```json
[{"queue_id": 42, "type": "scan_dir", "location_id": 1, "name": "Photos", "status": "running"}]
```

--------------------------------

### POST /api/auth/apps - Create application

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Creates a new application by sending a name in the request body. The response includes the generated ID and token.

```json
// Request
{"name": "My App"}

// Response
{"id": 1, "name": "My App", "token": "tok_..."}
```

--------------------------------

### POST /api/files/{id}/verify

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Starts background SHA-256 verification for the file's entire dup group.

```APIDOC
## POST /api/files/{id}/verify

### Description
Starts background SHA-256 verification for the file's entire dup group.

### Method
POST

### Endpoint
/api/files/{id}/verify

### Parameters
#### Path Parameters
- **id** (number) - Required - File ID.

### Response
#### Success Response (200)
- **verifying** (boolean) - Whether verification started.
- **filename** (string) - Filename.
- **groupSize** (number) - Size of dup group.

#### Response Example
```json
{"verifying": true, "filename": "photo.jpg", "groupSize": 3}
```
```

--------------------------------

### GET /api/auth/apps - List applications

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Returns a JSON array of registered applications with their IDs, names, tokens, and creation timestamps.

```json
[{"id": 1, "name": "My App", "token": "tok_...", "created_at": "2025-01-01T00:00:00"}]
```

--------------------------------

### GET /api/stats/repair-progress response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response for GET /api/stats/repair-progress. Shows the current repair status, active phase, and progress counters including hashed, total, skipped, errors, and stale.

```json
{
  "status": "running",
  "phase": "hashing",
  "hashed": 500, "total": 1000, "skipped": 50, "errors": 2, "stale": 3,
  ...
}
```

--------------------------------

### GET /api/search response

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Response body for GET /api/search. Contains items, folders, total, page, pageSize, and searchId. The page is always 0 in content mode and total is the number of items.

```json
{
  "items": [
    {"id": 123, "name": "photo.jpg", "rel_path": "2024/photo.jpg", ...}
  ],
  "folders": [],
  "total": 42,
  "page": 0,
  "pageSize": 120,
  "searchId": "s_abc123"
}
```

--------------------------------

### POST /api/restart

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Restarts the server.

```APIDOC
## POST /api/restart

### Description
Restarts the server.

### Method
POST

### Endpoint
/api/restart

### Response
#### Success Response (200)
- **message** (string) - Restart message

#### Response Example
```json
{"message": "Server restarting..."}
```
```

--------------------------------

### POST /api/batch/consolidate

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Batch consolidation in background.

```APIDOC
## POST /api/batch/consolidate

### Description
Batch consolidation in background.

### Method
POST

### Endpoint
/api/batch/consolidate

### Parameters
#### Request Body
- **file_ids** (array of numbers) - Required - IDs of files to consolidate.
- **mode** (string) - Required - `keep_here` or `move_to`.
- **consolidateMode** (string) - Required - `move` or `copy`.
- **destination_folder_id** (string) - Required - The destination folder ID.
- **filename_match_only** (boolean) - Optional - If true, only consider duplicates with matching filenames.

### Request Example
```json
{
  "file_ids": [123, 456],
  "mode": "keep_here",
  "consolidateMode": "move",
  "destination_folder_id": "fld-10",
  "filename_match_only": false
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{"message": "Batch consolidation started for 2 files"}
```
```

--------------------------------

### POST /api/themes

Source: https://github.com/zen-logic/file-hunter/blob/main/docs/API.md

Creates or overwrites a user theme.

```APIDOC
## POST /api/themes

### Description
Creates or overwrites a user theme.

### Method
POST

### Endpoint
/api/themes

### Parameters
#### Request Body
- **name** (string) - Required - Theme name
- **css** (string) - Required - CSS content
- **overwrite** (boolean) - Optional - Whether to overwrite existing theme

### Request Example
```json
{"name": "my-theme", "css": ":root { ... }", "overwrite": false}
```

### Response
#### Success Response (200)
- **saved** (string) - Saved theme name

#### Response Example
```json
{"saved": "my-theme"}
```
```