Bring your own vector store (BYOK knowledge)

ModuleX can retrieve from a vector store you already own instead of its managed store. You connect the store once as an org credential, then point a knowledge node at it by setting provider_type to the store’s name. ModuleX embeds the query, queries your store over its API, and formats the matches back into the workflow run state. This is the bring-your-own-key (BYOK) path for retrieval. Unlike managed knowledge — which is hosted in modulexdb and billed in credits — BYOK retrieval is uncosted: ModuleX never charges a retrieval credit when a knowledge node reads from an external provider. See credits for the full metering model.

BYOK here means retrieval only. ModuleX does not ingest, chunk, or embed your documents into an external store — you own that pipeline and load vectors into the store yourself. ModuleX reads from a collection you have already populated. Document upload and ingest (pending to processing to completed) apply to managed knowledge bases only; see managing documents.

Supported providers

Four external vector stores ship as knowledge providers. Each is browsable in the catalog via knowledge providers and has its own connection reference page.

Qdrant

High-performance vector store with payload filtering. provider_type value: qdrant.

Pinecone

Managed serverless and pod-based vector store with namespaces. provider_type value: pinecone.

MongoDB Atlas

Atlas Vector Search over your existing collections. provider_type value: mongodb_atlas.

Weaviate

Open-source vector store with cloud and self-hosted instances. provider_type value: weaviate.

The managed store, modulexdb, is the fifth provider type and the default. It is documented separately under managed knowledge and modulexdb. The provider_type field on a knowledge node accepts exactly these five values: modulexdb, qdrant, pinecone, weaviate, mongodb_atlas.

How retrieval works

A knowledge node configured for an external provider runs the same way on every run surface (builder, run from chat, and run via API):

Resolve the query

The node resolves its query string, including any {{node_id.field}} references to upstream node output. If query_from_input is true, the workflow input is used instead.

Load and decrypt the credential

ModuleX loads the org credential named by credential_id, scoped to your X-Organization-ID, and decrypts the connection fields (URL, API key, connection string) at runtime. See data security & encryption.

Embed the query

External stores receive a query vector, not text, so ModuleX embeds the query using the node’s embedding_config. Use the same embedding model your vectors were created with, or matches will be meaningless. If the embedding model is a managed (modulexai) model, the embedding step is billed in credits; a BYOK embedding model is uncosted.

Query your store

ModuleX calls your store’s query API with the vector, collection_name, top_k, min_score, and any filters / namespace. No retrieval credit is reserved or charged for this step.

Format and write to state

Matches are normalized into chunks and shaped by output_format, then written to run state under the node’s id (the standard node output convention).

All four external providers require a query embedding vector. You must set embedding_config on the knowledge node — omitting it raises a runtime error: embedding_config required for providers that don't handle embeddings. This includes Weaviate: although Weaviate supports nearText, the ModuleX adapter always sends a precomputed vector.

Connecting a provider

You connect an external store as an organization credential, then reference that credential from a knowledge node. Connecting requires the owner or admin role; the retired member role cannot create credentials. See roles & permissions.

In the app

Open the integration in knowledge providers, choose Connect, and fill in the connection fields for that store (below). ModuleX validates the connection with a live test call before saving, then stores the fields encrypted. Manage the saved credential later under managing credentials.

Connection fields per provider

Each provider uses the custom auth type. The fields below are exactly the credential fields the store’s auth schema declares — pass them inside auth_data when connecting via the API.

Qdrant
Pinecone
MongoDB Atlas
Weaviate

string

required

URL of your Qdrant instance, including the port. Example: https://xyz-abc.aws.cloud.qdrant.io:6333. Not sensitive.

string

API key for Qdrant Cloud. Optional for local instances. Sensitive.

The connection test lists collections via GET {url}/collections.

string

required

Your Pinecone API key (format pcsk_...). Sensitive.

string

required

Pinecone environment, for example us-east-1-aws or gcp-starter. Not sensitive.

The connection test lists indexes via GET https://api.pinecone.io/indexes.

string

required

MongoDB Atlas connection string, for example mongodb+srv://user:password@cluster.mongodb.net/. Sensitive (it carries credentials).

The connection test lists databases on the cluster.

string

required

URL of your Weaviate instance, for example https://your-cluster.weaviate.cloud. Not sensitive.

string

API key for Weaviate Cloud. Optional for local instances. Sensitive.

The connection test checks cluster status.

Connecting via the API

Create the credential with POST /credentials. The credential type is auto-detected from the body: send auth_type: "custom" plus the provider’s connection fields under auth_data, and set integration_name to the provider name (qdrant, pinecone, mongodb_atlas, or weaviate). Set make_default: true to make it the org’s default credential for that provider. Every request authenticates with Authorization: Bearer mx_live_… and X-Organization-ID. A successful create returns 201.

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: org_123" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "qdrant",
    "display_name": "Prod Qdrant",
    "auth_type": "custom",
    "make_default": true,
    "auth_data": {
      "url": "https://xyz-abc.aws.cloud.qdrant.io:6333",
      "api_key": "qdrant-api-key-..."
    }
  }'

from modulex import Modulex

client = Modulex(
    api_key="mx_live_xxx",
    organization_id="org_123",
)

credential = await client.credentials.create(
    integration_name="qdrant",
    display_name="Prod Qdrant",
    auth_type="custom",
    make_default=True,
    auth_data={
        "url": "https://xyz-abc.aws.cloud.qdrant.io:6333",
        "api_key": "qdrant-api-key-...",
    },
)
print(credential.credential_id)

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_xxx",
  organizationId: "org_123",
});

const credential = await client.credentials.create({
  integrationName: "qdrant",
  displayName: "Prod Qdrant",
  authType: "custom",
  makeDefault: true,
  authData: {
    url: "https://xyz-abc.aws.cloud.qdrant.io:6333",
    apiKey: "qdrant-api-key-...",
  },
});
console.log(credential.credentialId);

Validate before you save (POST /credentials/test-temporary)

To check connection fields without persisting a credential, post them to POST /credentials/test-temporary with integration_name, auth_type, and auth_data. The response reports validity and the test method:

{
  "is_valid": true,
  "message": "Credential is valid for qdrant",
  "tested_at": "2026-06-21T12:00:00",
  "test_method": "api_call",
  "integration_name": "qdrant",
  "auth_type": "custom",
  "status_code": 200,
  "cost_level": "free"
}

test_method is one of api_call, basic, or none. To re-test a credential you already saved, post to POST /credentials/{credential_id}/test. See managing credentials for the full credential lifecycle (create, set-default, rotate, delete).

Configuring the knowledge node

Once the credential exists, set the knowledge node provider_type to the store and reference the credential. The full node configuration follows.

Parameters

string

required

The credential connecting to the external store. Must belong to the request’s organization.

string

default:"modulexdb"

The store to query. One of modulexdb, qdrant, pinecone, weaviate, mongodb_atlas. Set it to the external provider’s name for BYOK retrieval.

string

required

The search query. Supports {{node_id.field}} references so the query can come from upstream node output.

boolean

default:"false"

When true, use the workflow input as the query instead of query. ModuleX reads the first of query, question, input, user_input, or message from run state. Prefer a {{...}} reference in query instead; this flag is retained for backward compatibility.

string

required

The collection / index / class to search. Required for every external provider — omitting it raises collection_name is required for external provider. The field maps to the store’s own concept: a Qdrant collection, a Pinecone index, a Weaviate class, or a MongoDB collection. Not used by modulexdb.

string

A namespace within the collection, for stores that support one (Pinecone). Passed through to the store’s query.

object

required

How ModuleX embeds the query before sending the vector to your store. Required for all four external providers. See the embedding fields below.

integer

default:"5"

Number of results to retrieve. Range 1 to 50.

number

default:"0.3"

Minimum similarity score, 0.0 to 1.0. Scores are normalized to this range per the store’s metric before filtering.

integer

default:"2000"

Maximum tokens in the formatted context string, applied only when output_format is context or both. Range 100 to 10000.

object

Provider-specific filter conditions passed to the store’s query (for example a Qdrant filter, a Pinecone metadata filter, or a MongoDB MQL pre-filter).

array

Restrict results to specific document IDs. Native (modulexdb) knowledge bases only — ignored by external providers; use filters instead.

string

default:"context"

Shape of the result written to state. One of chunks (matched chunks with metadata), context (a single RAG-ready string), or both.

boolean

default:"true"

Include each chunk’s metadata in the results.

boolean

default:"true"

Include a source header ([n] (Source: …, Score: …)) in the formatted context. For external providers the source is read from metadata.filename or metadata.source, falling back to Unknown.

Embedding config fields

string

required

The embedding provider’s integration name, for example openai, voyage, or cohere.

string

required

The provider identifier, for example openai or voyage.

string

required

The embedding model, for example text-embedding-3-small. Match the model your stored vectors were created with.

string

The credential for the embedding provider. If omitted, ModuleX uses the organization’s default credential for integration_name. If no default exists, the node fails with No default credential found for integration.

Output (written to run state)

The node writes a single object to run state under its node id, regardless of provider:

integer

Number of matches returned by the store.

array

Present when output_format is chunks or both; otherwise null. Each chunk:

Show chunk object

string

The chunk text, extracted from the match payload.

number

Normalized similarity score, 0.0 to 1.0.

object

The match metadata, or null when include_metadata is false.

string

The store’s match identifier.

string

Present when output_format is context or both; otherwise null. A single string joining the top chunks (token-budgeted by max_tokens), each prefixed with [n] and, when include_source is true, a (Source: …, Score: …) header.

When the query resolves to empty or the node errors at run time, it does not crash the run. Instead it writes {chunks: [], context: "", total_results: 0, error: "<message>"} to state so downstream nodes can branch on it. Combine this with a conditional node to handle no-result cases.

Worked example

A two-node workflow: an LLM node rewrites the user question, then a knowledge node retrieves from a Qdrant collection using that rewritten query and an OpenAI embedding model. The query references the LLM node’s output via {{rewrite.text}}.

{
  "id": "retrieve",
  "type": "knowledge",
  "config": {
    "provider_type": "qdrant",
    "credential_id": "a1b2c3d4-0000-0000-0000-000000000000",
    "collection_name": "product_docs",
    "query": "{{rewrite.text}}",
    "top_k": 8,
    "min_score": 0.4,
    "output_format": "both",
    "include_metadata": true,
    "include_source": true,
    "filters": { "must": [ { "key": "lang", "match": { "value": "en" } } ] },
    "embedding_config": {
      "integration_name": "openai",
      "provider_id": "openai",
      "model_id": "text-embedding-3-small",
      "credential_id": null
    }
  }
}

{
  "id": "retrieve",
  "type": "knowledge",
  "config": {
    "provider_type": "pinecone",
    "credential_id": "a1b2c3d4-0000-0000-0000-000000000000",
    "collection_name": "product-docs",
    "namespace": "v2",
    "query": "{{rewrite.text}}",
    "top_k": 8,
    "output_format": "context",
    "embedding_config": {
      "integration_name": "openai",
      "provider_id": "openai",
      "model_id": "text-embedding-3-small"
    }
  }
}

{
  "retrieve": {
    "total_results": 8,
    "chunks": [
      {
        "id": "chunk-4271",
        "score": 0.83,
        "content": "To install the CLI, run npm install -g modulex-cli ...",
        "metadata": { "filename": "install.md", "lang": "en" }
      }
    ],
    "context": "[1] (Source: install.md, Score: 0.83) To install the CLI, run npm install -g modulex-cli ..."
  }
}

A later node reads the retrieved context with {{retrieve.context}} (for context/both) or iterates {{retrieve.chunks}} (for chunks/both). See variables & references for the reference syntax and run a workflow for triggering the run end to end.

Credit impact

BYOK retrieval is uncosted

A knowledge node reading from qdrant, pinecone, weaviate, or mongodb_atlas never reserves or charges a retrieval credit. Only managed (modulexdb) retrieval is billed, at one retrieval credit per call. See credits and usage gating.

Two cost nuances remain:

Run credit. Every workflow run still costs the flat run credit, independent of which provider a knowledge node uses. See credits.
Embedding cost. If embedding_config points at a managed (modulexai) embedding model, embedding the query is billed in credits like any managed token usage. Point embedding_config at a BYOK embedding credential to keep the whole retrieval path uncosted.

Because BYOK retrieval is never gated, an external-provider knowledge node does not emit the billing DenialEnvelope (402 / 403 / 429). The billing gate that protects managed retrieval is skipped for BYOK. Your store’s own quotas and rate limits still apply, and they surface as run errors (see below), not as ModuleX billing denials.

Errors

External-provider knowledge nodes fail at run time rather than at request validation. A failure is captured into the node’s state object as an error field; the run continues so you can branch on it.

Condition	Message
`collection_name` missing for an external provider	`collection_name is required for external provider: <type>`
`embedding_config` missing	`embedding_config required for providers that don't handle embeddings`
`credential_id` not found in the org	`Credential not found: <id>`
Embedding `credential_id` not found	`Embedding credential not found: <id>`
No default embedding credential and none specified	`No default credential found for integration '<name>'`
Store auth or connectivity failure	The provider adapter raises a connection, authentication, or query error, surfaced in `error`

Validation errors on the credential API (for example a malformed body, or MCP-only fields) return the standard {detail} HTTPException shape with status 400 or 500. For the full envelope taxonomy across surfaces, see errors & status codes.

Knowledge providers

Browse the managed and external knowledge providers ModuleX can use.

Knowledge node

The node that retrieves from any provider inside a workflow.

Managed knowledge

The credit-billed modulexdb store, with ingest and search.

Knowledge & RAG

The retrieval model behind chats and workflows.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

Bring your own vector store (BYOK knowledge)

Supported providers

Qdrant

Pinecone

MongoDB Atlas

Weaviate

How retrieval works

Connecting a provider

In the app

Connection fields per provider

Connecting via the API

Configuring the knowledge node

Parameters

Embedding config fields

Output (written to run state)

Worked example

Credit impact

BYOK retrieval is uncosted

Errors

Knowledge providers

Knowledge node

Managed knowledge

Knowledge & RAG

​Supported providers

Qdrant

Pinecone

MongoDB Atlas

Weaviate

​How retrieval works

​Connecting a provider

​In the app

​Connection fields per provider

​Connecting via the API

​Configuring the knowledge node

​Parameters

​Embedding config fields

​Output (written to run state)

​Worked example

​Credit impact

BYOK retrieval is uncosted

​Errors

​Related

Knowledge providers

Knowledge node

Managed knowledge

Knowledge & RAG

Supported providers

How retrieval works

Connecting a provider

In the app

Connection fields per provider

Connecting via the API

Configuring the knowledge node

Parameters

Embedding config fields

Output (written to run state)

Worked example

Credit impact

Errors

Related