Skip to main content
POST
Upload File

Overview

Upload one or more files from a server-visible path into a text namespace. The server reads the file from disk (no HTTP multipart body), chunks it with the bundled Python chunker, generates batch summaries every 100 chunks, embeds each chunk, and stores them for search.
Path-based upload only (v1). Copy or mount files under ~/.moorcheh/uploads on the host (mounted read-only as /uploads in the container). API requests must use container paths such as /uploads/document.pdf.
Supported extensions: .pdf, .docx, .xlsx, .pptx, .txt, .csv, .md, .json. The job runs asynchronously. Poll File job status with the returned job_id.

Path parameters

string
required
Target text namespace.

Headers

string
required
Must be application/json

Body

array
required
Non-empty array of file objects.
string
required
Absolute path inside the server container. Use /uploads/... for files under the default upload mount.
boolean
default:"false"
When true, re-chunk and replace the index even if file_size and file_mtime match a previous upload.
any
Optional extra keys on each file object are merged into chunk metadata (for example "department": "engineering").

File identity and deduplication

  • file_id is server-generated: first 16 hex chars of sha256(namespace + NUL + absolute_path).
  • Skip re-upload when the same path already exists with the same file_size and file_mtime, unless force_reindex is true.
  • Chunk ids: {file_id}_chunk_{index}. Summary ids: {file_id}_summary_{batch}.
  • Each content chunk metadata includes summary_chunk_id (bare id, e.g. abc_summary_0) linking to its batch summary.

Request example

Response fields

string
"success" when the upload job started or all files were skipped.
string
Human-readable result.
string
Async job id when at least one file is uploading. Poll File job status.
string
Target namespace.
number
Number of file entries in the request.
number
Files accepted into the upload job.
array
Files skipped as already indexed (same size/mtime). Each entry includes file_id, absolute_path, and message.

Errors

Item limit is checked during the upload job (not at POST time). If exceeded, the job finishes with status: "failed" and last_error like "Item limit exceeded: max …, current …, requested … new items." — poll File job status.

Important notes

  • Use container paths (/uploads/...) in direct API calls — not Windows or macOS host paths.
  • The CLI moorcheh upload-file accepts a host path under ~/.moorcheh/uploads and converts it for you.
  • Upload indexes content only; deleting the index later does not remove the file on disk.