131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# API Contract
|
|
|
|
Base URL prefix: `/api/v1`
|
|
|
|
Primary implementation modules:
|
|
- `backend/app/api/router.py`
|
|
- `backend/app/api/routes_health.py`
|
|
- `backend/app/api/routes_documents.py`
|
|
- `backend/app/api/routes_search.py`
|
|
- `backend/app/api/routes_processing_logs.py`
|
|
- `backend/app/api/routes_settings.py`
|
|
|
|
## Health
|
|
|
|
- `GET /health`
|
|
- Purpose: liveness check
|
|
- Response: `{ "status": "ok" }`
|
|
|
|
## Documents
|
|
|
|
### Collection and metadata helpers
|
|
|
|
- `GET /documents`
|
|
- Query: `offset`, `limit`, `include_trashed`, `only_trashed`, `path_prefix`, `path_filter`, `tag_filter`, `type_filter`, `processed_from`, `processed_to`
|
|
- Response model: `DocumentsListResponse`
|
|
- `GET /documents/tags`
|
|
- Query: `include_trashed`
|
|
- Response: `{ "tags": string[] }`
|
|
- `GET /documents/paths`
|
|
- Query: `include_trashed`
|
|
- Response: `{ "paths": string[] }`
|
|
- `GET /documents/types`
|
|
- Query: `include_trashed`
|
|
- Response: `{ "types": string[] }`
|
|
- `POST /documents/content-md/export`
|
|
- Body model: `ContentExportRequest`
|
|
- Response: ZIP stream containing one markdown file per matched document
|
|
|
|
### Per-document operations
|
|
|
|
- `GET /documents/{document_id}`
|
|
- Response model: `DocumentDetailResponse`
|
|
- `GET /documents/{document_id}/download`
|
|
- Response: original file bytes
|
|
- `GET /documents/{document_id}/preview`
|
|
- Response: inline preview stream where browser-supported
|
|
- `GET /documents/{document_id}/thumbnail`
|
|
- Response: generated thumbnail image when available
|
|
- `GET /documents/{document_id}/content-md`
|
|
- Response: extracted markdown content for one document
|
|
- `PATCH /documents/{document_id}`
|
|
- Body model: `DocumentUpdateRequest`
|
|
- Response model: `DocumentResponse`
|
|
- `POST /documents/{document_id}/trash`
|
|
- Response model: `DocumentResponse`
|
|
- `POST /documents/{document_id}/restore`
|
|
- Response model: `DocumentResponse`
|
|
- `DELETE /documents/{document_id}`
|
|
- Behavior: permanent delete, requires document to be trashed first
|
|
- Response: deletion counters
|
|
- `POST /documents/{document_id}/reprocess`
|
|
- Response model: `DocumentResponse`
|
|
- Behavior: requeues asynchronous processing task
|
|
|
|
### Upload
|
|
|
|
- `POST /documents/upload`
|
|
- Multipart form fields:
|
|
- `files[]` (required)
|
|
- `relative_paths[]` (optional)
|
|
- `logical_path` (optional, defaults to `Inbox`)
|
|
- `tags` (optional CSV)
|
|
- `conflict_mode` (`ask`, `replace`, `duplicate`)
|
|
- Response model: `UploadResponse`
|
|
- Behavior:
|
|
- `ask`: returns `conflicts` if duplicate checksum is detected
|
|
- `replace`: creates new document linked to replaced document id
|
|
- `duplicate`: creates additional document record
|
|
|
|
## Search
|
|
|
|
- `GET /search`
|
|
- Query: `query` (min length 2), `offset`, `limit`, `include_trashed`, `only_trashed`, `path_filter`, `tag_filter`, `type_filter`, `processed_from`, `processed_to`
|
|
- Response model: `SearchResponse`
|
|
- Behavior: PostgreSQL full-text and metadata ranking
|
|
|
|
## Processing Logs
|
|
|
|
- `GET /processing/logs`
|
|
- Query: `offset`, `limit`, `document_id`
|
|
- Response model: `ProcessingLogListResponse`
|
|
- `POST /processing/logs/trim`
|
|
- Query: `keep_document_sessions`, `keep_unbound_entries`
|
|
- Response: trim counters
|
|
- `POST /processing/logs/clear`
|
|
- Response: clear counters
|
|
|
|
## Settings
|
|
|
|
- `GET /settings`
|
|
- Response model: `AppSettingsResponse`
|
|
- `PATCH /settings`
|
|
- Body model: `AppSettingsUpdateRequest`
|
|
- Response model: `AppSettingsResponse`
|
|
- `POST /settings/reset`
|
|
- Response model: `AppSettingsResponse`
|
|
- `PATCH /settings/handwriting`
|
|
- Body model: `HandwritingSettingsUpdateRequest`
|
|
- Response model: `AppSettingsResponse`
|
|
- `GET /settings/handwriting`
|
|
- Response model: `HandwritingSettingsResponse`
|
|
|
|
## Schema Families
|
|
|
|
Document schemas in `backend/app/schemas/documents.py`:
|
|
- `DocumentResponse`
|
|
- `DocumentDetailResponse`
|
|
- `DocumentsListResponse`
|
|
- `UploadConflict`
|
|
- `UploadResponse`
|
|
- `DocumentUpdateRequest`
|
|
- `SearchResponse`
|
|
- `ContentExportRequest`
|
|
|
|
Processing log schemas in `backend/app/schemas/processing_logs.py`:
|
|
- `ProcessingLogEntryResponse`
|
|
- `ProcessingLogListResponse`
|
|
|
|
Settings schemas in `backend/app/schemas/settings.py`:
|
|
- Provider, task, upload-default, display, predefined paths or tags, handwriting-style, and legacy handwriting models grouped under `AppSettingsResponse` and `AppSettingsUpdateRequest`.
|