ledgerdock/doc/api-contract.md

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: optional keep_document_sessions, keep_unbound_entries
  • Behavior: omitted query values fall back to persisted /settings.processing_log_retention
  • 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, processing-log retention, predefined paths or tags, handwriting-style, and legacy handwriting models grouped under AppSettingsResponse and AppSettingsUpdateRequest.