Upload Documents

curl -X POST "http://localhost:8080/namespaces/my-documents/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc-1",
        "text": "Moorcheh on-prem retrieval test",
        "team": "ai"
      }
    ]
  }'

{
  "status": "success",
  "message": "Documents upload started. Poll job status for progress.",
  "job_id": "job-a0e3d54b9d0d4616949474697308a39c",
  "namespace_name": "my-documents",
  "total": 1
}

{
  "status": "failure",
  "message": "Bad Request: documents must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each document must include non-empty 'id' and 'text'."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' is not a text namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 99999, requested 2 new items.",
  "items": 99999,
  "max_items": 100000,
  "requested_new": 2
}

POST

namespaces

{namespace_name}

documents

curl -X POST "http://localhost:8080/namespaces/my-documents/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc-1",
        "text": "Moorcheh on-prem retrieval test",
        "team": "ai"
      }
    ]
  }'

{
  "status": "success",
  "message": "Documents upload started. Poll job status for progress.",
  "job_id": "job-a0e3d54b9d0d4616949474697308a39c",
  "namespace_name": "my-documents",
  "total": 1
}

{
  "status": "failure",
  "message": "Bad Request: documents must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each document must include non-empty 'id' and 'text'."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' is not a text namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 99999, requested 2 new items.",
  "items": 99999,
  "max_items": 100000,
  "requested_new": 2
}

Overview

Upload one or more documents to a text namespace. Each document is embedded with the configured Ollama model and stored for semantic search. The upload runs asynchronously. Poll Upload job status with the returned job_id.

Any extra fields on each document object (for example team, source) are stored as metadata and can be used in search filters.

Path parameters

string

required

Target text namespace.

Headers

string

required

Must be application/json

Body

array

required

Non-empty array of document objects.

string

required

Item id, unique within this namespace.

string

required

Document text to embed and store.

any

Optional additional keys on each document are saved as metadata (for example "team": "ai").

curl -X POST "http://localhost:8080/namespaces/my-documents/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc-1",
        "text": "Moorcheh on-prem retrieval test",
        "team": "ai"
      }
    ]
  }'

Response fields

string

Request outcome. "success" when the upload job was started; "failure" on error.

string

Human-readable result or error description.

string

Id of the async upload job. Poll Upload job status with this value. Present when the upload job was started.

string

Namespace the documents are being uploaded to. Present when the upload job was started.

number

Number of documents accepted into the upload job. Present when the upload job was started.

number

Current total item count on the instance. Present on 409 item limit errors.

number

Global item cap for this instance. Present on 409 item limit errors.

number

Number of new item ids in the request that would exceed the cap. Present on 409 item limit errors.

{
  "status": "success",
  "message": "Documents upload started. Poll job status for progress.",
  "job_id": "job-a0e3d54b9d0d4616949474697308a39c",
  "namespace_name": "my-documents",
  "total": 1
}

{
  "status": "failure",
  "message": "Bad Request: documents must be a non-empty array."
}

{
  "status": "failure",
  "message": "Bad Request: each document must include non-empty 'id' and 'text'."
}

{
  "status": "failure",
  "message": "Namespace 'my-embeddings' is not a text namespace."
}

{
  "status": "failure",
  "message": "Namespace 'my-documents' not found."
}

{
  "status": "failure",
  "message": "Item limit exceeded: max 100000, current 99999, requested 2 new items.",
  "items": 99999,
  "max_items": 100000,
  "requested_new": 2
}

Important Notes

At most 100,000 items total across all namespaces
409 is returned before the job starts if new ids would exceed the cap
Re-uploading an existing id in the same namespace updates the item and does not consume extra quota

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

Overview

Path parameters

Headers

Body

Response fields

Important Notes

Next Steps

​Overview

​Path parameters

​Headers

​Body

​Response fields

​Important Notes

​Next Steps

​Related

Overview

Path parameters

Headers

Body

Response fields

Important Notes

Next Steps

Related