ModuleX managed knowledge (modulexdb)

Managed knowledge is the ModuleX-hosted vector store, identified on the wire by the provider name modulexdb. When a knowledge base embeds on the managed pool, ModuleX provisions the embedding model, runs the parse → chunk → embed pipeline, stores vectors in the managed vector store, and serves retrieval — and meters that work in credits. This page is the exact reference for the embedding and chunking configuration, the ingest and retrieval pipelines, what each operation costs, the billing gate that can deny managed work, and worked examples in three languages. A knowledge base is managed when its embedding_config.integration_name is modulexai. Any other value makes the knowledge base bring-your-own-key (BYOK) — you supply the vector store and embedding credential, and that usage is never credited (see External knowledge providers). Everything on this page about credit cost and the billing gate applies only to managed (modulexdb) knowledge bases.

Managed knowledge usage is gated. Managed ingest and managed retrieval pass through the ModuleX billing admission gate before any embedding runs. When your plan allowance or wallet is exhausted, or a rate limit is hit, the gate returns a flat DenialEnvelope as 402 / 403 / 429 and no document or search result is produced. The plain knowledge CRUD routes (create, list, update a knowledge base) are not gated and return the ordinary {detail} error shape instead. See The billing gate below and Usage gating & limits.

How managed knowledge fits together

Managed knowledge is one configuration of a knowledge base, not a separate object. The same knowledge base, documents, and chunks back both managed and BYOK knowledge — only the embedding provider differs.

Embedding configuration

embedding_config is a per-knowledge-base JSON object that controls which model produces the vectors. ModuleX reads the keys defensively, so two naming conventions are accepted for the same settings; document and accept both.

Key drift — two accepted conventions. The model default uses provider + model_id, while the service default uses integration_name + provider_id + model_id + credential_id. The embed code reads either spelling: provider or provider_id, model or model_id, provider_credential_id or credential_id. The managed-vs-BYOK decision is made only on integration_name == "modulexai", so a managed knowledge base must set integration_name.

string

default:"openai"

The ModuleX integration that owns the embedding pool. Set to modulexai to make the knowledge base managed (billed in credits). Any other value (for example openai, cohere) is treated as BYOK and is not credited.

string

default:"openai"

The actual embedding provider. Validated against openai, cohere, azure, huggingface, but only openai and cohere have an embedding implementation — anything else raises Unsupported embedding provider at embed time. Also accepted under the key provider.

string

default:"text-embedding-3-small"

The embedding model. Also accepted under the key model. For managed knowledge bases the model resolves through the ModuleX model pool so that ingest-time and search-time vectors are produced by the same model.

integer

default:"1536"

The embedding vector dimension. Range 64–4096. The embedding vector is sized for the default 1536 (the text-embedding-3-small dimension); text-embedding-3-large supports up to 4096. Out-of-range values are rejected at create or update with a KnowledgeBaseValidationError → 400.

string

The embedding credential. Also accepted as provider_credential_id. If omitted, ModuleX auto-discovers an org credential whose integration exposes an embedding-capable model (integration_type == "llm_provider" with a model where is_embedding is true). If none exists, create fails with NoEmbeddingCredentialError → 400.

A managed embedding_config looks like this:

{
  "integration_name": "modulexai",
  "provider_id": "openai",
  "model_id": "text-embedding-3-small",
  "dimension": 1536,
  "credential_id": "a1b2c3d4-0000-4000-8000-000000000001"
}

Chunking configuration

chunking_config controls how each document is split before embedding. It is validated on create and merged-then-revalidated on update.

string

default:"recursive"

The chunking strategy. One of recursive (a recursive character splitter that prefers the configured separators), token (a fixed token window using the cl100k_base tokenizer), or simple (a fixed character window). Any other value is rejected with a KnowledgeBaseValidationError → 400.

integer

default:"1000"

Target chunk size. Range 100–4000. For token strategy this is a token count; for the others it is a character count.

integer

default:"200"

Overlap between adjacent chunks. Range 0–500, and it cannot exceed 50% of chunk_size. The default 200 is 20% of the default chunk_size of 1000. A breach raises KnowledgeBaseValidationError → 400.

string[]

default:"[\"\\n\\n\", \"\\n\", \" \", \"\"]"

Ordered separators tried by the recursive strategy, from coarsest to finest. The default is paragraph, then line, then word, then character. Ignored by token and simple.

A default chunking_config:

{
  "strategy": "recursive",
  "chunk_size": 1000,
  "chunk_overlap": 200,
  "separators": ["\n\n", "\n", " ", ""]
}

Storage, documents, and chunks

Each managed knowledge base stores three kinds of records. The id values below are UUIDs.

object

The knowledge base itself: name, description, the embedding_config and chunking_config above, a status of active / processing / error / archived, and an auto-created linked credential_id so workflow knowledge nodes can reference it.

object

One per uploaded file: filename, file_type, file_size_bytes, a file_hash (a content hash, used for in-knowledge-base deduplication), a status of pending / processing / completed / failed, chunk_count, token_count, and an error_message when ingest fails.

object

One per chunk: the chunk content, its token_count, chunk_index, start_char / end_char, and the embedding vector. Chunks are what retrieval searches over.

Document limits

These limits apply to managed and BYOK knowledge bases alike.

Limit	Value	Notes
Supported file types	`pdf`, `docx`, `doc`, `txt`, `md`, `html`, `csv`, `json`, `xlsx`, `pptx`	Resolved from the file extension first, then MIME type.
Documents per knowledge base	`500`	Hard cap.
Per-file size cap	Plan entitlement	The enforced cap is your plan’s `max_file_size_bytes` (Free 10 MB, Pro 50 MB, Max 100 MB, Enterprise unlimited), not a flat 50 MB. The `/knowledge-bases/info/supported-file-types` endpoint advertises 50 MB as a fallback, but the plan value is authoritative.
Total org storage	Plan entitlement	Free 1 GiB, Pro 50 GiB, Max 500 GiB, Enterprise unlimited.

The upload cap is a plan entitlement, not a fixed 50 MB. A document larger than your plan’s max_file_size_bytes, or one that would push your org over its storage quota, is rejected with a KnowledgeBaseQuotaExceededError → 403 carrying the ordinary {detail} shape — not the billing DenialEnvelope. See Managing documents and Plans & pricing.

Credit cost of ingest and retrieval

Managed knowledge is metered with flat per-operation credits plus the token-metered embedding cost. One credit is worth $0.01 (100 credits = $1.00). BYOK knowledge bases incur none of these charges. The authoritative cost reference is Credits & metering.

Operation	`usage_type`	Flat cost (credits)	Plus token cost	When charged
Document ingest	`file_ingest`	1	Per-document embedding tokens (input-only) recorded by the worker	Reserved before the upload write; recorded once per document on success
Knowledge search / hybrid / retrieve-context	`retrieval`	1	Query-embedding tokens (input-only) recorded on success	Reserved before the query is embedded; recorded on success
Multi-knowledge-base search	`retrieval`	1 total	Query-embedding tokens (see caveat below)	One retrieval base if any searched knowledge base is managed

integer

default:"1"

Credits reserved per managed document ingest (usage_type="file_ingest"). Charged once per document and idempotent on the document ID, so a retry of an unchanged document is not double-charged.

integer

default:"1"

Credits reserved per managed retrieval (usage_type="retrieval"), covering /search, /hybrid-search, /retrieve-context, and multi-knowledge-base search.

The embedding token cost is computed as input tokens only — embedding forces completion_tokens to 0 — and added to the flat base. The full formula and the credit unit live in Credits & metering.

Reprocessing a document does not re-charge the flat base. Retrying a failed document or reprocessing one does not run the ingest gate again, and the per-document embedding cost is keyed on {doc_id}:embedding:{token_count}, so an unchanged reprocess is not re-charged. A document whose content changed enough to produce a different token count will record a fresh embedding cost.

Multi-knowledge-base search records embedding tokens for the last knowledge base only. A POST /knowledge-bases/search across several knowledge bases reserves exactly one retrieval base credit (if any of them is managed), but the per-query embedding token cost is recorded for the last searched knowledge base only — a known in-code accounting gap. The flat retrieval credit is always correct; the token line may undercount across several managed knowledge bases.

The ingest pipeline

When you upload a document to a managed knowledge base, this is what happens, in order:

Poll a document’s processing with GET /knowledge-bases/{kb_id}/documents/{document_id}/status; the full document and chunk APIs are covered in Managing documents.

Ingest a document

curl -X POST https://api.modulex.dev/knowledge-bases/7c1e8b2a-0000-4000-8000-000000000abc/documents \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: org_123" \
  -F "file=@manual.pdf" \
  -F 'metadata={"tags":["product"]}'

import asyncio
from modulex import ModuleX

async def main():
    async with ModuleX(
        api_key="mx_live_xxx",
        organization_id="org_123",
    ) as mx:
        with open("manual.pdf", "rb") as f:
            doc = await mx.knowledge_bases.documents.upload(
                "7c1e8b2a-0000-4000-8000-000000000abc",
                file=f,
                metadata={"tags": ["product"]},
            )
        print(doc.id, doc.status)  # -> "pending"

asyncio.run(main())

import { ModuleX } from "modulex";
import { createReadStream } from "node:fs";

const mx = new ModuleX({
  apiKey: "mx_live_xxx",
  organizationId: "org_123",
});

const doc = await mx.knowledgeBases.documents.upload(
  "7c1e8b2a-0000-4000-8000-000000000abc",
  {
    file: createReadStream("manual.pdf"),
    metadata: { tags: ["product"] },
  },
);
console.log(doc.id, doc.status); // -> "pending"

The upload accepts multipart/form-data with a required file part and an optional metadata part (a JSON string; invalid JSON → 400 {"detail":"Invalid metadata JSON"}). The response is the new document with status pending:

{
  "id": "d1f0a3b4-0000-4000-8000-0000000000d1",
  "knowledge_base_id": "7c1e8b2a-0000-4000-8000-000000000abc",
  "filename": "manual.pdf",
  "file_type": "pdf",
  "file_size_bytes": 820341,
  "status": "pending",
  "chunk_count": 0,
  "token_count": 0,
  "error_message": null,
  "created_at": "2026-06-20T12:00:00"
}

The retrieval pipeline

A managed retrieval embeds your query, then runs a cosine vector search over the knowledge base’s chunks. The flat retrieval credit is reserved before the query is embedded, so an exhausted allowance denies the search before any model call. There are four retrieval shapes:

Route	What it returns
`POST /knowledge-bases/{kb_id}/search`	Top-`k` chunks by cosine similarity.
`POST /knowledge-bases/{kb_id}/hybrid-search`	Vector results blended with keyword full-text ranking, by `keyword_weight` / `semantic_weight`.
`POST /knowledge-bases/{kb_id}/retrieve-context`	A single token-budgeted context string with `[Source: ...]` headers, ready to feed an LLM prompt.
`POST /knowledge-bases/search`	Multi-knowledge-base search: merges and re-ranks results across several knowledge bases.

Search parameters

These are the parameters for POST /knowledge-bases/{kb_id}/search.

string

required

The search query. Minimum length 1. It is embedded with the knowledge base’s embedding_config model and compared against stored chunk vectors.

integer

default:"5"

Number of chunks to return. Range 1–50.

number

default:"0.0"

Minimum cosine similarity, computed as 1 - distance. Range 0.0–1.0. Chunks below the floor are dropped. In hybrid-search the floor instead applies to the combined weighted score, so the two scales are not identical.

object

Optional filters. Supports document_id and document_ids to scope the search to specific documents.

boolean

default:"true"

Whether to include each chunk’s text content in the matches.

boolean

default:"true"

Whether to include each chunk’s metadata in the matches.

Search a managed knowledge base

curl -X POST https://api.modulex.dev/knowledge-bases/7c1e8b2a-0000-4000-8000-000000000abc/search \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: org_123" \
  -H "Content-Type: application/json" \
  -d '{"query":"how to install","top_k":5,"min_score":0.2}'

import asyncio
from modulex import ModuleX

async def main():
    async with ModuleX(
        api_key="mx_live_xxx",
        organization_id="org_123",
    ) as mx:
        result = await mx.knowledge_bases.search(
            "7c1e8b2a-0000-4000-8000-000000000abc",
            query="how to install",
            top_k=5,
            min_score=0.2,
        )
        for match in result.matches:
            print(match.score, match.document_filename)

asyncio.run(main())

import { ModuleX } from "modulex";

const mx = new ModuleX({
  apiKey: "mx_live_xxx",
  organizationId: "org_123",
});

const result = await mx.knowledgeBases.search(
  "7c1e8b2a-0000-4000-8000-000000000abc",
  { query: "how to install", topK: 5, minScore: 0.2 },
);
for (const match of result.matches) {
  console.log(match.score, match.documentFilename);
}

The response carries the matched chunks with their cosine score:

string

The query you sent, echoed back.

string

The knowledge base searched.

integer

The effective top_k.

integer

How many chunks matched at or above min_score.

object[]

The ranked matches.

Show match object

string

The chunk’s id.

string

The source document’s id.

string

The source document’s filename.

integer

The chunk’s position within its document.

number

Cosine similarity, 1 - distance.

string

The chunk text, present when include_content is true.

object

The chunk metadata, present when include_metadata is true.

{
  "query": "how to install",
  "knowledge_base_id": "7c1e8b2a-0000-4000-8000-000000000abc",
  "top_k": 5,
  "total_matches": 3,
  "matches": [
    {
      "chunk_id": "c1a2b3c4-0000-4000-8000-0000000000c1",
      "document_id": "d1f0a3b4-0000-4000-8000-0000000000d1",
      "document_filename": "manual.pdf",
      "chunk_index": 4,
      "score": 0.83,
      "content": "To install, download the package and run the setup script.",
      "metadata": {}
    }
  ]
}

Retrieve a RAG context string

For feeding an LLM, retrieve-context returns one token-budgeted string instead of a list of chunks. It takes query (required), max_tokens (100–10000, default 2000), top_k (1–50, default 10), and min_score (0.0–1.0, default 0.3), and returns {context, query} where context joins the selected chunks with [Source: <filename>, Chunk <n>] headers. It is billed identically to /search — one retrieval credit plus the query-embedding token cost.

Inside a workflow

A knowledge node resolves a managed knowledge base from its linked credential and retrieves at run time. Its output_format selects what the node writes into run state — chunks, context, or both — and downstream nodes read it with a {{node_id.field}} reference (see Variables & references). Retrieval inside a workflow is metered through the same managed-retrieval path as the REST API, so it costs the same 1 retrieval credit plus query-embedding tokens.

The billing gate (402 / 403 / 429)

Managed ingest and managed retrieval flow through the ModuleX usage gate. On denial the gate returns a flat DenialEnvelope — {code, layer, key, current, limit, reason} — at the status that matches the layer. This is a different shape from the ordinary {detail} errors that the plain knowledge CRUD routes return.

Status	`layer`	Typical `code`	Cause
`402`	`credit`	`credit_plan_exhausted`	Plan credit allowance exhausted (and no wallet overage).
`402`	`wallet`	`wallet_overage_disabled` / `wallet_insufficient`	Allowance gone and wallet overage is off or the balance is too low.
`403`	`quota`	`quota_exceeded`	A metered quota was hit at the gate.
`429`	`rate`	`rate_limit_exceeded`	Per-minute rate limit hit. Carries `Retry-After` (default `60`) and `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`.

A 402 credit denial looks like this — note there is no detail wrapper:

{
  "code": "credit_plan_exhausted",
  "layer": "credit",
  "key": "org_123",
  "current": null,
  "limit": 5000.0,
  "reason": "credit_plan_exhausted"
}

Two error contracts coexist on the knowledge surface. Managed-ingest and managed-retrieval credit / rate / quota denials use the flat DenialEnvelope above. Knowledge-base count quota and per-file / storage limits raise a KnowledgeBaseQuotaExceededError → 403 carrying the ordinary {"detail": "..."} shape — not the envelope. Branch on both. The full taxonomy is on Errors & status codes.

The Python SDK maps these by status to typed errors — 402 → PaymentRequiredError (with CreditExhaustedError / WalletError subclasses), 403 → PermissionError / QuotaExceededError, 429 → RateLimitError. See Errors & retries and Usage gating & limits.

Other errors

These are the non-billing errors managed-knowledge operations can return. They use the ordinary {"detail": "..."} shape.

error

Invalid embedding_config or chunking_config (out-of-range dimension, chunk size, overlap, or an unknown strategy), invalid status on update, or an unsupported embedding provider configuration.

error

An empty file, a duplicate file (same content hash already in the knowledge base), an unsupported file type, or invalid metadata JSON. Also returned when retrying a document that is not in the failed state.

error

No embedding credential was supplied and none could be auto-discovered for the org.

error

KnowledgeBaseQuotaExceededError (knowledge-base count, per-file size, or storage quota), or SearchAccessDeniedError / DocumentAccessDeniedError when the caller lacks access.

error

KnowledgeBaseNotFoundError or DocumentNotFoundError. A wrong-org document also returns 404, not 403.

error

Pydantic request validation failed — for example a missing required query, or a missing file part on upload.

error

The embedding call failed — including Unsupported embedding provider when the configured provider has no embedding implementation. SearchServiceError covers other retrieval-time failures.

Authentication

Every managed-knowledge request requires an API key and an organization context. Knowledge routes require the owner or admin role; the retired member role cannot call them (see Roles & permissions).

Headers

Authorization: Bearer mx_live_xxx
X-Organization-ID: org_123
Content-Type: application/json

The backend also accepts the API key as X-API-KEY: mx_live_xxx. Use Authorization: Bearer for new code.

Credits & metering

The credit unit, the per-operation cost table, and the reserve → charge → settle lifecycle.

Usage gating & limits

The admission gate and its 402 / 403 / 429 DenialEnvelope responses.

Managing documents

Upload, monitor processing, retry, and manage documents and chunks.

External knowledge providers

Bring your own vector store — Qdrant, Pinecone, MongoDB Atlas, Weaviate — uncredited.

modulexdb (managed)

The managed vector store as a knowledge provider.

Knowledge node

Retrieve from a managed knowledge base inside a workflow.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

Managed knowledge (modulexdb)

How managed knowledge fits together

Embedding configuration

Chunking configuration

Storage, documents, and chunks

Document limits

Credit cost of ingest and retrieval

The ingest pipeline

Ingest a document

The retrieval pipeline

Search parameters

Search a managed knowledge base

Retrieve a RAG context string

Inside a workflow

The billing gate (402 / 403 / 429)

Other errors

Authentication

Credits & metering

Usage gating & limits

Managing documents

External knowledge providers

modulexdb (managed)

Knowledge node

​How managed knowledge fits together

​Embedding configuration

​Chunking configuration

​Storage, documents, and chunks

​Document limits

​Credit cost of ingest and retrieval

​The ingest pipeline

​Ingest a document

​The retrieval pipeline

​Search parameters

​Search a managed knowledge base

​Retrieve a RAG context string

​Inside a workflow

​The billing gate (402 / 403 / 429)

​Other errors

​Authentication

​Related pages

Credits & metering

Usage gating & limits

Managing documents

External knowledge providers

modulexdb (managed)

Knowledge node

How managed knowledge fits together

Embedding configuration

Chunking configuration

Storage, documents, and chunks

Document limits

Credit cost of ingest and retrieval

The ingest pipeline

Ingest a document

The retrieval pipeline

Search parameters

Search a managed knowledge base

Retrieve a RAG context string

Inside a workflow

The billing gate (402 / 403 / 429)

Other errors

Authentication

Related pages