<!-- module: lookup -->
<!-- description: File lookup by name and unregistration -->
<!-- depends: 01_auth, 03_register -->

## File Lookup

### `GET /api/v1/files/lookup`

**Auth**: Required
**Scope**: file-level

Search registered files by file name. Performs a case-insensitive LIKE search on the file name column. Returns basic info about matching files.

#### Query Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_name` | string | Yes | File name to search for (partial matches supported) |

#### Example

```bash
# Look up a specific file
curl -s "$API/api/v1/files/lookup?file_name=video.mp4" \
  -H "X-API-Key: $KEY"

# Partial name search
curl -s "$API/api/v1/files/lookup?file_name=charade" \
  -H "X-API-Key: $KEY" | jq '.matches[].file_name'
```

#### Response (200)

```json
{
  "file_name": "video.mp4",
  "exists": true,
  "matches": [
    {
      "file_uuid": "a03485a40b2df2d3",
      "file_name": "video.mp4",
      "file_type": "video",
      "status": "completed"
    }
  ],
  "next_name": "video (2).mp4"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `file_name` | string | Searched name |
| `exists` | boolean | Exact name match exists |
| `matches` | array | Array of matching registered files |
| `matches[].file_uuid` | string | 32-char hex UUID |
| `matches[].file_name` | string | Registered file name |
| `matches[].file_type` | string | `"video"`, `"audio"`, or `null` |
| `matches[].status` | string | Registration/processing status |
| `next_name` | string | Suggested name for avoiding conflicts |

---

## Unregister

### `POST /api/v1/unregister`

**Auth**: Required
**Scope**: file-level

Delete a registered file from the system. Supports single file by UUID, or batch by directory + regex pattern.

#### What gets deleted

| Removed (default) | Not removed |
|---------|-------------|
| Database records (videos, chunks, embeddings, processor_results, pre_chunks) | The original source video file on disk |
| Processor output JSON files (`{uuid}.*.json`) — unless `delete_output_files: false` | Temp/working directories |
| In-memory cache entries | |
| MongoDB cached lists | |

> ⚠️ Database deletion is **irreversible**. To keep output files, set `"delete_output_files": false`.

#### Request Parameters

At least one mode must be specified: either `file_uuid` alone, or `file_path` + `pattern` together.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `file_uuid` | string | * | — | Single file UUID to delete |
| `file_path` | string | * | — | Directory path (for batch delete) |
| `pattern` | string | * | — | Regex pattern (requires `file_path`) |
| `delete_output_files` | boolean | No | `true` | If `true`, also delete processor output JSON files (`{uuid}.*.json`). Set to `false` to keep them. |

#### Example

```bash
# Delete a single file by UUID (default: also deletes output JSON files)
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'"}'

# Keep output JSON files, only delete DB records
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "delete_output_files": false}'

# Batch delete all mp4 files in a directory
curl -s -X POST "$API/api/v1/unregister" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_path": "/path/to/dir", "pattern": ".*\\.mp4$"}'
```

#### Response (200)

```json
{
  "success": true,
  "file_uuid": "a03485a40b2df2d3",
  "message": "Video unregistered successfully"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | True if deletion succeeded |
| `file_uuid` | string | UUID of the deleted file (single mode) |
| `message` | string | Human-readable status |

#### Error Responses

| HTTP | When |
|------|------|
| `400` | Neither `file_uuid` nor `file_path`+`pattern` provided |
| `404` | File UUID not found |
| `401` | Missing or invalid API key |