Documents

List Documents

List documents, filtered by workspace, category, tags, kind, visibility or origin. Defaults to the current workspace; include_shared adds org-wide documents (workspace_id null). Paginated by limit and offset.

Query parameters

• category_idstring (uuid)optional

  Filter by specific category ID

• workspace_idstringoptional

  Filter by workspace ID (uses current workspace if not specified)

• tagsstringoptional

  Comma-separated category names to filter by

• kindenumoptional

  Filter by document role. kb returns only knowledge-base documents (the wizard's KB-doc step uses this); guideline returns only guideline documents. Omit to list every kind.

  kbguideline

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Get Document

Get document details

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Update Document

Update document metadata

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• filenamestringoptional
• descriptionstringoptional

Delete Document

Delete a document

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Update Document Categories

Replace all categories for a document

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• category_idsstring (uuid)[]required

Add Document To Category

Add document to category

Path parameters

• document_idstring (uuid)required
• category_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Remove Document From Category

Remove document from category

Path parameters

• document_idstring (uuid)required
• category_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Get Document Content

Return a txt/md document's text for editing. Served on /api/documents/{id}/content (dashboard) and /v1/documents/{id}/content (SDK). Other file types are refused: what comes out is what PUT can replace.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Update Document Content

Save a txt/md document's text; free to call on every autosave. Served on /api/documents/{id}/content (admin role) and /v1/documents/{id}/content (SDK, documents:write scope). Idempotency-Key required. DeepContext is not touched; call POST /documents/{id}/index once the writer is done.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• contentstringrequired

Get Document Diagnostics

Report DC ingest lifecycle health for one document. Returns a typed deviation list to branch on without parsing strings. Free read; documents:read suffices.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Update Extracted Text

Update extracted text content for a document

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Recompile Guideline

Force the guideline classify+distill pass for one document. Confirms a likely_kb verdict ("compile it anyway") or re-runs after a prompt-version bump. Enqueues with force=True, bypassing the classifier gate and the hash short-circuit. Tracked-only (0 credits); returns 202 with the task queued.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Index Document

Send a written document's saved text to DeepContext for search. Called when the writer leaves the document. A no-op when DeepContext already holds this text, so repeated calls are safe; indexed says whether anything was sent.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Keep Document As Reference

Keep an RFP-like document in the knowledge base on purpose. The flag records the choice so the check never asks again and retrieval can tell it from company material. "Start a proposal from it" needs no route: the client sends the same file to the proposal upload and deletes this document.

Path parameters

• document_idstring (uuid)required

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Preflight Documents

Check whether files would be accepted, before any byte moves. Returns one verdict per file, in order (a drop of twelve with room for ten admits the first ten), plus the room left. The upload remains the authority.

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• filesobject[]required
  Show 3 properties
• workspace_kindenumoptional
  dataguideline

Upload Document

Upload a document; indexing runs in the background. Poll processing_status for completion. Gated by the document_upload operation (max_documents, max_storage_gb).

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Form fields

• filefilerequired
• category_idsstringoptional
• kindenumoptional

  Document role override. When omitted, the document inherits the parent workspace's kind (data → kb, guideline → guideline) — the legacy implicit behaviour preserved for every existing caller. The KB pane upload defaults the kind via the workspace; the Guidelines pane upload routes through X-Workspace-ID to the guideline workspace and the kind seeds from there.

  kbguideline
• visible_in_workspace_idstring (uuid)optional

  Per-workspace visibility scope for guideline documents (mig 123). NULL (default) = org-wide visibility (today's behavior, preserved). Set to a data workspace id = the guideline is only visible from that workspace's wizard / Guidelines tab. Meaningful only for guideline-kind uploads; the service layer rejects this field on KB-kind uploads with a 400, mirroring the DB-level CHECK.

Upload Document Text

Upload a document as a raw markdown or plaintext JSON body. Same document_upload gating (scope, limits) and atomic credit commit as POST /upload. Only .md and .txt; binary formats need the multipart route.

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• filenamestringrequired
• contentstringrequired
• category_idsstring (uuid)[]optional
• index_on_leavebooleanoptional

Write Document

Start a model writing a document, the same writing Arthur's start_document starts. A new document's row exists on return, so its card can show at once. The text streams on GET /runs/{run_id}/stream as stage=document frames (snapshot | delta | complete); the run's lifecycle rides /runs/live with kind=document and the document_id.

Headers

• X-Organization-IDstringoptional
• X-Workspace-IDstringoptional

Request body

• instructionsstringoptional

  What the document should contain (new / rewrite / append).

• contextstringoptional

  Material to write from, sent whole.

• titlestringoptional
• modeenumoptional
  newrewriteappendedit