API Documentation

Quickstart — Chatbot in 5 Minutes

Go from zero to a working AI chatbot in 5 steps. All you need is an API key from the Console.

# Python
pip install fluxvector

from fluxvector import FluxVector

fv = FluxVector(api_key="fv_live_your_key")

# Create a knowledge base
fv.collections.create("my-docs")

# Upload your documents
fv.vectors.upsert("my-docs", [
    {"id": "1", "text": "Check-in is at 3pm, check-out at 11am"},
    {"id": "2", "text": "Pool is open 7am-10pm daily"},
    {"id": "3", "text": "WiFi password is guest2026"},
])

results = fv.search("my-docs", "pool hours")

for r in results:
    print(f"{r.score:.2f} — {r.text}")
# 0.94 — Pool is open 7am-10pm daily

answer = fv.answer.create("my-docs", "What time does the pool close?")

print(answer.answer)       # "The pool closes at 10pm. [1]"
print(answer.confidence)   # 0.95
print(answer.sources)      # [{index: 1, id: "2", score: 0.94}]

chat = fv.chat.create("my-docs", "Is there a pool?", session_id="guest-1")
print(chat.message)  # "Yes, the pool is open 7am-10pm daily. [1]"

# Follow-up — remembers context
chat2 = fv.chat.create("my-docs", "What about towels?", session_id="guest-1")

# Pass your own LLM key for faster, higher-quality generation
answer = fv.answer.create(
    "my-docs", "What time is check-in?",
    llm_provider="claude",
    llm_api_key="sk-ant-your-key",
)
# 300ms with Claude vs 4-30s with built-in Ollama

That's it. You have a chatbot backed by 8-signal search with anti-hallucination confidence. See more use cases or read the full API reference below.

Embeddable Widget

Add a chatbot to any website with one line of HTML. No code needed.

<script
  src="https://fluxvector.dev/static/widget.js"
  data-collection="my-docs"
  data-key="fv_live_your_key"
></script>

Optional attributes: data-llm-provider ("claude" or "openai"), data-llm-key, data-greeting, data-position ("right" or "left"), data-theme ("dark" or "light").

Authentication

All requests require a Bearer token in the Authorization header. Get your API key from the Console.

Authorization: Bearer fv_live_your_api_key_here

SDKs

# Python
pip install fluxvector

# TypeScript / Node.js
npm install @fluxsoft/fluxvector

# LangChain integration
pip install langchain-fluxvector

Search Modes

FluxVector supports 4 search modes via the mode parameter.

HyperSearch

Search a collection using up to 7 independent signals fused with proprietary scoring. Returns ranked results with confidence and anti-hallucination warnings.

curl -X POST https://fluxvector.dev/v1/search \
  -H "Authorization: Bearer $FV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection": "docs", "text": "how to deploy", "mode": "fusion", "top_k": 5}'

{
  "results": [
    {"id": "doc-1", "score": 0.8742, "text": "Deploy with Docker...",
     "metadata": {"category": "ops"},
     "score": 0.8742}
  ],
  "confidence": 0.87,
  "warning": null,
  "took_ms": 89,
  "cached": false
}

RAG Answer

Full RAG in one call: search with HyperSearch, generate an answer from retrieved documents, and cite sources. If confidence is too low, returns "I don't have reliable information" instead of hallucinating.

{
  "answer": "To deploy, use Docker Compose [1] and configure the environment variables [2]...",
  "confidence": 0.91,
  "sources": [{"index": 1, "id": "doc-1", "score": 0.92}],
  "generated": true
}

Agentic RAG

Multi-step iterative search. An AI agent analyzes results, rewrites queries, and searches again until confidence is high enough. Handles complex multi-faceted questions.

{
  "results": [...],
  "iterations": [
    {"iteration": 1, "query": "original question", "confidence": 0.32},
    {"iteration": 2, "query": "rewritten query", "confidence": 0.78}
  ],
  "total_iterations": 2,
  "confidence": 0.78
}

Conversational Chat

Stateful conversational RAG. Send a message with a session ID — the server maintains conversation history, searches the collection, and generates a contextual response with citations.

{
  "message": "The pool is open from 7am to 10pm. [1]",
  "confidence": 0.91,
  "sources": [{"index": 1, "id": "faq-2", "score": 0.93}],
  "generated": true,
  "session_id": "sess_abc123",
  "history_length": 4
}

Create Collection

Create a new vector collection.

List Collections

List all collections for your account with vector counts.

Delete Collection

Delete a collection and all its vectors. This is irreversible.

Upsert Vectors

Add or update documents. Text is automatically embedded with multiple models server-side.

{
  "collection": "docs",
  "vectors": [
    {"id": "1", "text": "Your document text", "metadata": {"category": "guide"}}
  ]
}

Delete Vectors

Delete vectors by ID from a collection.

Fetch Vectors

Retrieve vectors by their IDs. Max 500 per request.

Ingest URL

Crawl a URL, extract text, chunk it, and upsert all chunks into a collection. Handles HTML, plain text, and markdown.

{
  "ingested": true,
  "url": "https://example.com/docs",
  "doc_id": "abc123",
  "chunks": 12,
  "characters": 8500,
  "upserted": 12
}

Embed Text

Get the embedding vector for a single text. Useful for pre-computing embeddings or debugging.

Batch Embed

Embed multiple texts in one call. Batch limits depend on plan (Free: 5, Pro: 50, Scale: 100).

List Models

List all available embedding models with their dimensions and enabled status.

List MCP Tools

Returns MCP tool definitions that any AI agent (Claude, ChatGPT, etc.) can use to search FluxVector. Tools: fluxvector_search, fluxvector_answer, fluxvector_upsert, fluxvector_collections.

Execute MCP Tool

Execute a tool call from an AI agent. The agent sends the tool name and arguments, FluxVector runs the operation and returns formatted results.

Generate Synthetic Training Data

Generate hypothetical questions for documents in a collection. Creates (question, document) pairs for fine-tuning.

Flush Training Data

Flush collected training pairs from memory to the database.

Training Stats

Get counts of collected training pairs (real usage vs synthetic).