Upload and manage documents in a ModuleX knowledge base

Documents are the files you add to a knowledge base so ModuleX can answer from your own material. When you upload a file, ModuleX extracts its text, splits it into smaller passages called chunks, and turns each chunk into a searchable vector. This page is the hands-on guide to that lifecycle: how to add files, watch them process, fix the ones that fail, inspect their chunks, and remove the ones you no longer need. If you are setting up a knowledge base for the first time, start with Knowledge overview. For the ideas behind chunks, embeddings, and retrieval, see Knowledge & RAG.

Documents live inside a knowledge base, which belongs to your organization. Adding and managing documents requires the owner or admin role — see Roles & permissions. Every request is scoped to your organization by the X-Organization-ID header (see Org context).

Add documents

Open a knowledge base, then drag files onto the upload area or click to choose them. You can select several files at once; ModuleX uploads them one after another.

Choose your files

Drag and drop, or click the upload area and pick files. Each file is checked against the supported formats and your plan’s size limit before it is sent.

ModuleX uploads each file

Files upload one at a time. As soon as a file is accepted, it appears as a document with the status pending.

Processing starts automatically

ModuleX prepares each document in the background — extracting text, splitting it into chunks, and embedding each chunk. You can keep working while large files process. See Watch documents process.

Supported file types

A knowledge base accepts these formats. The file type is read from the file extension first, then from its content type if the extension is missing.

Documents

PDF (.pdf), Word (.docx, .doc), plain text (.txt), and Markdown (.md).

Web and structured data

HTML (.html), CSV (.csv), and JSON (.json).

Spreadsheets and slides

Excel (.xlsx) and PowerPoint (.pptx).

Check the live list

The app fetches the current list of supported types when you open the upload area, so it always matches what the service accepts.

A file must contain at least some extractable text. An empty file is rejected before processing begins.

Upload size is set by your plan

The largest file you can upload is a plan entitlement, not a single fixed cap. Although some older surfaces still mention a flat 50 MB limit, the value that is actually enforced comes from your organization’s plan:

Plan	Max file size per upload
Free	10 MB
Pro	50 MB
Max	100 MB
Enterprise	Unlimited

The static “supported file types” info that the upload area reads still advertises 50 MB regardless of plan. That number is a fallback only. The limit enforced when you actually upload is the plan value above — so on the Free plan a 40 MB file is rejected even though 50 MB is shown, and on the Max plan a 90 MB file is accepted. Treat your plan as the source of truth, and confirm your tier on Plans & pricing.

A second limit applies per knowledge base: there is a cap on how many documents a single knowledge base can hold, and your plan can set this too. If you hit it, delete some documents or use another knowledge base. See Plan limits for the full table.

Duplicate files are skipped

ModuleX fingerprints each file’s contents. If you upload a file whose contents exactly match a document already in that knowledge base, the upload is rejected as a duplicate rather than stored twice. Change the file (even slightly) or upload it to a different knowledge base if you genuinely need a second copy.

Add a note to a document (optional)

When you upload over the API, you can attach a small JSON object of metadata — for example {"tags": ["product"]} — to label or group documents. The metadata must be valid JSON; an invalid value is rejected. See Add documents over the API.

Watch documents process

Every document reports its progress, so you always know whether it is ready to search. While files are still being prepared, the app refreshes the status automatically every few seconds — you do not need to reload the page.

The four document states: pending, processing, completed, failed

A document moves through these states in order:

Pending — uploaded and waiting in the queue. No chunks yet.
Processing — being parsed, split into chunks, and embedded. This is where text extraction and vectorizing happen.
Completed — fully prepared. The document now has a chunk count and a token count, and its chunks are searchable.
Failed — something went wrong while preparing the file. The document keeps an error message explaining what happened, and you can retry it.

A failed document can be retried, which sends it back to pending and runs the preparation again. Only completed and failed documents appear in the document table; documents that are still pending or processing are shown as in-flight in the knowledge base header.

A completed document shows two useful numbers:

Chunk count

How many searchable passages the document was split into. More chunks usually means a longer document, or smaller chunk-size settings on the knowledge base.

Token count

The total number of tokens across the document’s chunks. This is what managed knowledge bases meter for embedding — see What processing costs.

Retry a failed document

If a document ends up failed, the most common causes are a corrupt file, an unreadable scan with no extractable text, or a format the parser could not open. Fix the source file if needed, then retry.

Open the failed document

Find the document in the table — failed documents show an error message that usually explains what went wrong.

Select retry

Retrying resets the document to pending, clears the old error and timestamps, and runs the preparation pipeline again from the start.

Watch it process again

The document moves back through processing to completed (or failed again if the underlying problem is not fixed).

Retry only works on a document that is in the failed state. There is no separate “reindex” action — retrying a failed document re-runs the full parse, chunk, and embed pipeline, which produces fresh chunks. To rebuild a document that already completed (for example after changing the file), delete it and upload the new version.

Retrying does not double-charge. On a managed (modulexdb) knowledge base, the embedding cost for a document is recorded against its content, so retrying an unchanged document does not spend embedding credits again. See What processing costs.

Inspect a document’s chunks

Once a document is completed, you can look at the individual chunks it was split into. This is the quickest way to understand why a search returns a particular passage, or to check that a document was extracted cleanly. Each chunk carries:

Field	What it is
`chunk_index`	The chunk’s position within the document, starting at `0`.
`content`	The chunk’s text.
`token_count`	How many tokens the chunk holds.
`start_char` / `end_char`	Where the chunk falls in the original document.
`has_embedding`	Whether the chunk has a searchable vector yet.
`metadata`	Any metadata carried with the chunk.

You can also run the knowledge base’s search test to preview which chunks a question returns, ranked by relevance — see Use a knowledge base.

Delete a document

Deleting a document removes it and all of its chunks from the knowledge base. By default it also removes the stored file. Deletion is permanent — there is no undo — so the document stops contributing to answers immediately.

Deleting a document removes its chunks from search right away. Any chat, the Assistant, or workflow that relied on that material will no longer find it. If you only want to pause a whole library rather than lose a file, archive the knowledge base instead — see Manage a knowledge base over time.

What processing costs

Whether preparing a document costs anything depends on where the knowledge base stores its vectors.

Managed (modulexdb)

On a managed knowledge base, ModuleX hosts the vector storage. Uploading and processing a document meters credits: a base ingest charge plus the embedding cost based on the document’s token count.

Bring your own (BYOK)

On a knowledge base pointed at your own vector store, ModuleX does not charge credits for processing — your provider bills you directly. See External knowledge providers.

On a managed knowledge base, an upload that would exceed your plan allowance can return a billing denial — a 402, 403, or 429 response carrying a {code, layer, key, current, limit, reason} envelope — instead of storing the document. Plan size and document-count limits, by contrast, return a 403 with a plain {detail} message. See Credits & metering, Usage gating & limits, and Errors & status codes.

Add documents over the API

Everything above is available programmatically. Upload is a multipart/form-data request: send the file as the file part, and an optional JSON metadata part. Authenticate every request the same way as every other endpoint — an Authorization: Bearer mx_live_… header plus X-Organization-ID (see Authentication).

# Upload a document to a knowledge base
curl -X POST https://api.modulex.dev/knowledge-bases/7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f/documents \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42" \
  -F "file=@manual.pdf" \
  -F 'metadata={"tags":["product"]}'

# List the documents in a knowledge base
curl https://api.modulex.dev/knowledge-bases/7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f/documents \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42"

# Check one document's processing status
curl https://api.modulex.dev/knowledge-bases/7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f/documents/d1f0a2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b/status \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42"

# Retry a failed document
curl -X POST https://api.modulex.dev/knowledge-bases/7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f/documents/d1f0a2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b/retry \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42"

# Delete a document
curl -X DELETE https://api.modulex.dev/knowledge-bases/7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f/documents/d1f0a2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42"

import asyncio
from modulex import Modulex

KB_ID = "7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f"


async def main():
    async with Modulex(
        api_key="mx_live_8Kd2pQ7rExample",
        organization_id="org_3xampleOrg42",
    ) as mx:
        # Upload a document
        with open("manual.pdf", "rb") as file:
            doc = await mx.knowledge.documents.upload(
                knowledge_base_id=KB_ID,
                file=file,
                metadata={"tags": ["product"]},
            )
        print(doc.id, doc.status)  # e.g. "...", "pending"

        # List the documents in the knowledge base
        documents = await mx.knowledge.documents.list(knowledge_base_id=KB_ID)
        for d in documents:
            print(d.id, d.filename, d.status, d.chunk_count)


asyncio.run(main())

import { readFileSync } from "node:fs";
import { Modulex } from "modulex";

const KB_ID = "7c1e8f20-1d2a-4b6c-9e3f-2a1b4c5d6e7f";

const client = new Modulex({
  apiKey: "mx_live_8Kd2pQ7rExample",
  organizationId: "org_3xampleOrg42",
});

// Upload a document
const doc = await client.knowledge.documents.upload({
  knowledgeBaseId: KB_ID,
  file: new Blob([readFileSync("manual.pdf")]),
  filename: "manual.pdf",
  metadata: { tags: ["product"] },
});
console.log(doc.id, doc.status); // e.g. "...", "pending"

// List the documents in the knowledge base
const documents = await client.knowledge.documents.list({
  knowledgeBaseId: KB_ID,
});
for (const d of documents) {
  console.log(d.id, d.filename, d.status, d.chunkCount);
}

A freshly uploaded document comes back with status pending. Poll its status to follow the move through processing to completed (or failed). A completed document reports its chunk_count and token_count; a failed one carries an error_message.

The exact SDK method names and argument shapes for document upload, list, status, retry, and delete are not yet pinned in the SDK reference; the snippets above show the operation and the request shape the REST API expects. For the authoritative per-operation signatures, see the SDKs overview and the SDK ⇄ API parity matrix.

Where to go next

Knowledge overview

Create a knowledge base, set its chunking, and use it across chats and workflows.

Managed knowledge (modulexdb)

How ModuleX-hosted vector storage and retrieval work, and what they cost.

Knowledge & RAG

The concepts behind documents: chunks, embeddings, ingest, and retrieval.

Build a RAG knowledge base

A start-to-finish guide: create a knowledge base, ingest documents, and query it.

Credits & metering

What a credit is and exactly what processing a document consumes.

Chat with your knowledge

Ask questions in chat answered from your completed documents.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

Upload and manage documents

Add documents

Supported file types

Documents

Web and structured data

Spreadsheets and slides

Check the live list

Upload size is set by your plan

Duplicate files are skipped

Add a note to a document (optional)

Watch documents process

Chunk count

Token count

Retry a failed document

Inspect a document’s chunks

Delete a document

What processing costs

Managed (modulexdb)

Bring your own (BYOK)

Add documents over the API

Where to go next

Knowledge overview

Managed knowledge (modulexdb)

Knowledge & RAG

Build a RAG knowledge base

Credits & metering

Chat with your knowledge

​Add documents

​Supported file types

Documents

Web and structured data

Spreadsheets and slides

Check the live list

​Upload size is set by your plan

​Duplicate files are skipped

​Add a note to a document (optional)

​Watch documents process

Chunk count

Token count

​Retry a failed document

​Inspect a document’s chunks

​Delete a document

​What processing costs

Managed (modulexdb)

Bring your own (BYOK)

​Add documents over the API

​Where to go next

Knowledge overview

Managed knowledge (modulexdb)

Knowledge & RAG

Build a RAG knowledge base

Credits & metering

Chat with your knowledge

Add documents

Supported file types

Upload size is set by your plan

Duplicate files are skipped

Add a note to a document (optional)

Watch documents process

Retry a failed document

Inspect a document’s chunks

Delete a document

What processing costs

Add documents over the API

Where to go next