Save Document To Sqlite
POST /api/writing/documents/save
💾 Save a document (create or update).
Single HTTP entry point for every document save. Delegates to
WritingDocumentStore.save_html which is the unified save path
used by every save site in the application.
Save guarantees:
- The .docx file is written atomically with fsync. Power loss after the rename cannot lose the bytes.
- SQLite metadata is updated as a follow-up. If that fails, the
response carries
metadataCommitted: falseand the reconciler will repair the metadata on its next pass — but the user’s bytes are already safe on disk.
Returns: SaveDocumentResponse with the saved document.
Always HTTP 200 on a successful disk write, even on metadata drift.
Errors:
- 400
HTML_PARSE_FAILED— TipTap HTML couldn’t be parsed. - 500
DOCX_BUILD_FAILED— python-docx couldn’t build the document. - 507
DISK_WRITE_FAILED— disk full / permission / I/O error. - 500
ENCRYPTION_FAILED— manuscript encryption step failed. - 500
ATOMIC_RENAME_FAILED— final rename failed (original untouched).
Request Body required
Section titled “Request Body required ”Request body for the unified save endpoint.
Used by POST /api/writing/documents/save. The endpoint is the single
HTTP entry point for all document saves (create or update); it routes
through WritingDocumentStore.save_html.
Fields: title: Document title (required). content: TipTap HTML content (required, may be empty for blank docs). document_id: Existing document ID for update; omit for create. document_type: Free-form document classifier; defaults to “general”. tags: Tag list. Replaces the existing tag set on update.
Responses
Section titled “ Responses ”Successful Response
Response body for the unified save endpoint.
Always returned with HTTP 200 for both create and update successes.
The metadata_committed flag distinguishes a fully committed save
from a successful disk write where the SQLite metadata update lagged
(the reconciler will repair the latter on its next pass).
Fields:
document_id: ID of the saved document.
title: Saved title.
content: Saved TipTap HTML, echoed back so the client doesn’t need
to round-trip through a load.
document_type: Saved document type.
tags: Saved tag list.
word_count: Word count derived from the parsed block list (no
disk re-read).
file_path: Absolute path to the on-disk .docx file.
modified_at: Modification timestamp in milliseconds since epoch.
outcome: "created" or "updated".
metadata_committed: True if SQLite metadata write succeeded; False
if disk write succeeded but metadata update lagged. The save
is durable in either case.
object
Validation Error