Skip to main content
modulexdb is the ModuleX-managed vector store — the built-in knowledge provider you select when you want ModuleX to host the vectors and run the embeddings for you, with no external vector database to provision. It is one of the knowledge providers ModuleX can retrieve from; the others (Qdrant, Pinecone, MongoDB Atlas, and Weaviate) are bring-your-own-key (BYOK) stores that you connect with your own credentials. Choosing modulexdb is the difference between managed and BYOK retrieval. When a knowledge base embeds on the managed pool, ModuleX provisions the embedding model, stores the vectors in pgvector, serves retrieval, and meters that work in credits. BYOK providers are never credited — that usage is billed by your upstream vector store and embedding provider.
This page is the provider-catalog entry for modulexdb: how to select it as a provider for a knowledge base and for a workflow knowledge node, what it costs, and how the billing gate behaves. The exhaustive reference for the managed store itself — the full embedding and chunking schema, the ingest and retrieval pipelines, document and chunk records, and the per-operation REST surface — is Managed knowledge (modulexdb). Read that page for the deep mechanics; this page tells you how to wire modulexdb in.

​
When to choose modulexdb

Managed — modulexdb

ModuleX hosts the vectors in pgvector and provisions the embedding model. No external store to run. Ingest and retrieval are billed in credits. Best when you want RAG to work out of the box.

BYOK — Qdrant, Pinecone, Atlas, Weaviate

You bring the vector store and the embedding credential. ModuleX queries it on your behalf. Usage is not credited by ModuleX — your provider bills you directly. Best when you already run a vector database.
A knowledge base is managed when its embedding_config.integration_name is modulexai (the managed integration name on the wire). The provider name modulexdb is how the same managed store is referenced from a knowledge node and in the provider catalog. Both point at the same hosted pgvector store; everything on this page about credit cost and the billing gate applies only to it.
🎬 MEDIA PLACEHOLDER · MX-MEDIA-4120 · [IMAGE] [IMAGE_DESCRIPTION]: Managed vs BYOK knowledge provider decision diagram for ModuleX. [IMAGE_DETAILS]: Two columns. Left: “modulexdb (managed)” with sub-items “ModuleX-hosted pgvector”, “managed embeddings”, “billed in credits”. Right: “BYOK (Qdrant / Pinecone / Atlas / Weaviate)” with “your vector store”, “your embedding credential”, “not credited by ModuleX”. A shared box at the top reads “Knowledge base / knowledge node”. Light theme, 16:9, brand palette.

​
Selecting modulexdb for a knowledge base

You select the managed store at the knowledge-base level through embedding_config. Set integration_name to modulexai and ModuleX treats the knowledge base as managed; on create it also auto-creates a linked credential so workflow knowledge nodes can reference the knowledge base by credential_id.
​
embedding_config.integration_name
string
default:"openai"
The ModuleX integration that owns the embedding pool. Set to modulexai to make the knowledge base managed (modulexdb, billed in credits). Any other value — for example openai or cohere — is treated as BYOK and is not credited. This single field is what decides managed vs BYOK.
​
embedding_config.provider_id
string
default:"openai"
The actual embedding provider behind the managed pool. Validated against openai, cohere, azure, huggingface, but only openai and cohere have an embedding implementation; any other value raises Unsupported embedding provider at embed time. Also accepted under the key provider.
​
embedding_config.model_id
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 come from the same model.
​
embedding_config.dimension
integer
default:"1536"
The embedding vector dimension. Range 64–4096. The pgvector column is sized for the default 1536 (the text-embedding-3-small dimension). Out-of-range values are rejected at create or update with a KnowledgeBaseValidationError → 400.
​
embedding_config.credential_id
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. If none exists, create fails with NoEmbeddingCredentialError → 400.
Two accepted key spellings. ModuleX reads embedding_config defensively: 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.
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"
}
For the chunking schema, document and chunk records, storage backends, and the full ingest and retrieval pipelines, see Managed knowledge (modulexdb).

​
Selecting modulexdb in a workflow knowledge node

A knowledge node retrieves from a provider inside a running workflow. To retrieve from the managed store, set the node’s provider_type to modulexdb and point credential_id at the managed knowledge base’s linked credential. modulexdb is the default provider_type for a knowledge node.
​
credential_id
string
required
The credential ID for the knowledge base. For modulexdb this is the credential ModuleX auto-created when the managed knowledge base was created. ModuleX resolves the knowledge base from the credential’s stored knowledge_base_id.
​
provider_type
string
default:"modulexdb"
The knowledge provider. One of modulexdb, qdrant, pinecone, weaviate, mongodb_atlas. Use modulexdb for the managed store. The external values require a BYOK credential and, for most of them, a collection_name.
​
top_k
integer
default:"5"
Number of results to retrieve. Range 1–20.
​
min_score
number
default:"0.3"
Minimum cosine-similarity score threshold. Range 0.0–1.0. Matches below this score are dropped.
​
max_tokens
integer
default:"2000"
Maximum tokens in the formatted context string, when the node returns a RAG context. Range 100–8000.
​
collection_name
string
Collection or index name. Not used for modulexdb (the managed store needs no collection). Required for external providers such as Qdrant and Pinecone.
​
namespace
string
Namespace for Pinecone or similar providers. Not used for modulexdb.
​
embedding_config
object
Embedding configuration for external providers that do not embed internally. Not used for modulexdb, which carries its own embedding_config on the knowledge base.
A managed knowledge-node config: 
{
  "credential_id": "939f74dc-7b2f-473c-b87d-b95c30c32fd3",
  "provider_type": "modulexdb",
  "top_k": 5,
  "min_score": 0.3
}

​
Credit cost of managed knowledge

modulexdb is the only knowledge provider that consumes credits. A credit is the managed-usage billing unit: **1000 credits = 1.00∗∗(‘1‘credit=‘1.00** (`1` credit = `0.001`). Two operations are metered, each as a flat base credit plus the input-only embedding token cost.
OperationFlat base creditPlusWhen it is charged
File ingest1 per documentthe document’s embedding token cost (input-only), recorded by the ingest workerOnce per document, idempotent on the document ID. A retry of an unchanged document is not re-charged.
Retrieval1 per callthe query-embedding token cost (input-only), recorded on successOnce per search, hybrid-search, retrieve-context, or multi-knowledge-base search.
A multi-knowledge-base search charges one retrieval base if any queried knowledge base is managed, regardless of order. Creating, listing, or updating a knowledge base is not credit-gated.
The embedding token cost uses the standard token-metering formula with input tokens only (embeddings have no completion tokens): cost = prompt_tokens · in_rate / 1e6 · MARGIN · SCALE, where MARGIN is 1.05 (a 5% system margin) and SCALE is 1000. BYOK providers run the same searches but record no credit cost. For the full credit model, see Credits & metering; for what each plan allows, see Plans & pricing.

​
The billing gate (402 / 403 / 429)

Managed ingest and managed retrieval pass through the ModuleX billing admission gate before any embedding runs. The gate fails closed: when your plan allowance or wallet is exhausted, a quota is exceeded, or a rate limit is hit, it returns a flat DenialEnvelope and no document or search result is produced. The DenialEnvelope is a flat object — there is no detail wrapper — of the shape {code, layer, key, current, limit, reason}:
​
code
string
The machine-readable denial reason, for example credit_plan_exhausted, quota_exceeded, or rate_limit_exceeded.
​
layer
string
The gate layer that denied the call. Maps to the HTTP status: credit → 402, wallet → 402, quota → 403, rate → 429.
​
key
string | null
The denied resource key, for example the organization UUID or the rate class. May be null.
​
current
number | null
The current usage at the time of denial. May be null.
​
limit
number | null
The limit that was hit. May be null.
​
reason
string
The denial reason, mirroring code.
{
  "code": "credit_plan_exhausted",
  "layer": "credit",
  "key": "<org_uuid>",
  "current": null,
  "limit": 25000.0,
  "reason": "credit_plan_exhausted"
}
A 429 carries Retry-After (default 60) and X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers.
Two different denial shapes coexist for managed knowledge. The credit, wallet, quota, and rate gate denials use the flat DenialEnvelope above. Document-level limits — a file larger than your plan’s max_file_size_bytes, exceeding the documents-per-knowledge-base cap, or running out of storage quota — are raised as a KnowledgeBaseQuotaExceededError → 403 with the ordinary {detail} shape, not the DenialEnvelope. Branch on both. See Usage gating & limits and Errors & status codes.

​
Worked example — search a managed knowledge base

Every request authenticates with Authorization: Bearer mx_live_… plus the X-Organization-ID header (see Authentication). Searching a managed knowledge base reserves 1 retrieval credit before the query is embedded. 
curl -X POST https://api.modulex.dev/knowledge-bases/7c1e.../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.3}'
The SDK method names and parameter casing for the knowledge-base search operation are not fully pinned in the research base. The cURL request and its body are verified against the backend; the Python and JavaScript snippets above show the standard ModuleX client shape and should be confirmed against the JavaScript SDK and Python SDK references before relying on the exact method names.
A successful response returns the matching chunks with cosine-similarity scores. The full request and response schema for every managed knowledge operation — search, hybrid search, retrieve-context, multi-knowledge-base search, ingest, and document management — lives in Managed knowledge (modulexdb).

​
Limits

These document limits apply to every knowledge base, managed or BYOK.
LimitValue
Supported file typespdf, docx, doc, txt, md, html, csv, json, xlsx, pptx
Documents per knowledge base500
Per-file size capYour plan’s max_file_size_bytes (Free 10 MB, Pro 50 MB, Max 100 MB, Enterprise unlimited)
Total org storageYour plan’s storage entitlement (Free 1 GiB, Pro 50 GiB, Max 500 GiB, Enterprise unlimited)
The per-file cap is a plan entitlement, not a fixed 50 MB. The /knowledge-bases/info/supported-file-types endpoint advertises 50 MB as a fallback, but the enforced cap is your plan value. See Managing documents.

Managed knowledge (modulexdb)

The full technical reference: embedding and chunking schema, ingest and retrieval pipelines, and the per-operation REST surface.

Knowledge providers

Compare modulexdb with the BYOK vector stores.

Knowledge node

Retrieve from modulexdb inside a workflow.

Credits & metering

What a credit is and exactly what managed knowledge consumes.