VectorAI Developer API Reference

🚀 Quickstart Guide

Follow these 3 simple steps to integrate VectorAI into your RAG pipelines or microservices:

1. Get your API Key

Sign in to the VectorAI Developer Console to generate a workspace API key (e.g. sk-lvl1-9988aabbcc...).

2. Ingest Document Content

Send raw text, PDF, DOCX, or CSV URLs to the ingestion gateway. VectorAI automatically chunks, embeds, and indexes your document:

curl -X POST https://vector.acadmyai.com/v1/ingest \
  -H "Authorization: Bearer sk-lvl1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_text": "AcadmyAI delivers zero-trust security, vector databases, and quantitative market telemetry across financial and enterprise sectors.",
    "collection_name": "enterprise_kb",
    "chunking_strategy": "recursive",
    "chunk_size": 512,
    "chunk_overlap": 64
  }'

# pip install vectorai-sdk
from vectorai import VectorClient

client = VectorClient(api_key="sk-lvl1-your_api_key_here")

# Ingest text (or pass file_path="doc.pdf" with client.ingest_file)
result = client.ingest(
    raw_text="AcadmyAI delivers zero-trust security, vector databases, and quantitative market telemetry across financial and enterprise sectors.",
    collection_name="enterprise_kb",
    chunking_strategy="recursive",
    chunk_size=512,
    chunk_overlap=64
)
print(f"Chunks created: {result.chunks_created} | Doc ID: {result.doc_id}")

const response = await fetch("https://vector.acadmyai.com/v1/ingest", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-lvl1-your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    raw_text: "AcadmyAI delivers zero-trust security, vector databases, and quantitative market telemetry across financial and enterprise sectors.",
    collection_name: "enterprise_kb",
    chunking_strategy: "recursive",
    chunk_size=512,
    chunk_overlap=64
  })
});

const data = await response.json();
console.log(data);

3. Perform Sub-45ms Semantic Search

Query your collection with natural language queries to retrieve the highest scoring contextual vector chunks:

curl -X POST https://vector.acadmyai.com/v1/search \
  -H "Authorization: Bearer sk-lvl1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What products does AcadmyAI provide?",
    "collection_name": "enterprise_kb",
    "limit": 3,
    "hybrid": true
  }'

# pip install vectorai-sdk
from vectorai import VectorClient

client = VectorClient(api_key="sk-lvl1-your_api_key_here")

# Sub-45ms Semantic Search with Hybrid BM25 & Neural Rerank
results = client.search(
    query="What products does AcadmyAI provide?",
    collection_name="enterprise_kb",
    limit=3,
    hybrid=True,  # BM25 lexical keyword + dense vector Reciprocal Rank Fusion
    rerank=True   # Cross-encoder neural reranker
)

for item in results:
    print(f"[{item.score:.4f}] {item.text}")

const response = await fetch("https://vector.acadmyai.com/v1/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-lvl1-your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What products does AcadmyAI provide?",
    collection_name: "enterprise_kb",
    limit: 3,
    hybrid: true
  })
});

const results = await response.json();
console.log(results);

🌐 Base URL & Environments

All programmatic endpoints are served over secure HTTPS. For local testing with our dockerized sandbox, use the localhost base URL:

🔐 API Keys & Authentication

VectorAI uses standard Bearer Token authentication. Pass your workspace API key in the Authorization header with all requests:

Authorization: Bearer sk-lvl1-9988aabbcc112233445566778899aabb

🐍 Python SDK (vectorai-sdk)

The official Python SDK provides an idiomatic, high-throughput client for vector ingestion, hybrid semantic search, balance tracking, LangChain/LlamaIndex vector store adapters, and a terminal CLI.

Installation

# Standard SDK
pip install vectorai-sdk

# With LangChain support
pip install "vectorai-sdk[langchain]"

# With LlamaIndex support
pip install "vectorai-sdk[llamaindex]"

Synchronous Client Quickstart

API keys can be passed explicitly via api_key="..." or auto-detected from the VECTORAI_API_KEY environment variable.

from vectorai import VectorClient

# Initialize client (API Key is mandatory)
client = VectorClient(api_key="sk-lvl1-9988aabbcc112233445566778899aabb")

# 1. Ingest raw text or local document file
result = client.ingest(
    raw_text="VectorAI delivers sub-45ms hybrid semantic vector retrieval for enterprise RAG.",
    collection_name="enterprise_kb",
    chunking_strategy="recursive",
    chunk_size=512,
    chunk_overlap=64,
    metadata={"source": "whitepaper", "year": 2026}
)
print(f"Ingested {result.chunks_created} chunks | Doc ID: {result.doc_id}")

# Ingest local file directly (PDF, DOCX, CSV, Text, Markdown)
file_result = client.ingest_file(
    file_path="./quarterly_earnings_report.pdf",
    collection_name="finance_kb"
)

# 2. Sub-45ms Semantic Search with Hybrid RRF & Neural Rerank
response = client.search(
    query="What is the retrieval latency of VectorAI?",
    collection_name="enterprise_kb",
    limit=3,
    hybrid=True,  # BM25 lexical keyword + dense vector Reciprocal Rank Fusion
    rerank=True   # Cross-encoder neural reranker
)

for item in response:
    print(f"[{item.score:.4f}] Chunk #{item.chunk_index}: {item.text}")

# 3. Check Leftover Quota & Subscription Balances
usage = client.get_usage()
print(f"Plan Tier: {usage.tier} | Days Left: {usage.days_remaining}")
print(f"Chunks Stored: {usage.quota.total_chunks_stored} / {usage.quota.max_chunks_allowed}")
print(f"Chunks Remaining: {usage.chunks_remaining}")

Asynchronous Client (AsyncVectorClient)

For high-throughput FastAPI microservices and async worker tasks:

import asyncio
from vectorai import AsyncVectorClient

async def run_query():
    async with AsyncVectorClient(api_key="sk-lvl1-...") as client:
        results = await client.search(
            query="quantum encryption standards",
            collection_name="security_kb",
            limit=5
        )
        for r in results:
            print(r.score, r.text)

asyncio.run(run_query())

LangChain & LlamaIndex Integrations

Drop VectorAI directly into your existing LangChain or LlamaIndex RAG pipelines:

# LangChain Drop-In
from vectorai.integrations.langchain import VectorAIStore

vectorstore = VectorAIStore(
    api_key="sk-lvl1-...",
    collection_name="product_kb"
)

# Add texts
vectorstore.add_texts(["VectorAI is built for enterprise AI pipelines"])

# Create LangChain retriever
retriever = vectorstore.as_retriever(search_kwargs={"k": 3, "hybrid": True})
docs = retriever.get_relevant_documents("How to integrate VectorAI?")

Terminal CLI Tool (vectorai)

Execute semantic searches, ingest local directories, and inspect quotas directly from your terminal:

# Ingest local file
vectorai ingest ./quarterly_report.pdf --collection finance --strategy recursive

# Run semantic search from terminal
vectorai search "What was our operating cash flow?" --collection finance --limit 3 --hybrid

# Inspect remaining chunk quota & plan expiration
vectorai quota

# Verify cluster SLA health
vectorai health

Document Ingestion API

{
  "doc_id": "8e3fb2a1-4352-479c-b17d-948f219198ab",
  "status": "success",
  "collection_name": "enterprise_kb",
  "chunks_created": 6,
  "chunking_strategy": "recursive",
  "chunk_size": 512,
  "chunk_overlap": 64,
  "vector_dimensions": 384,
  "provider": "huggingface",
  "embedding_model": "financial"
}

Semantic Search API

{
  "query": "What products does AcadmyAI provide?",
  "collection_name": "enterprise_kb",
  "profile_used": "default",
  "total_returned": 2,
  "results": [
    {
      "id": 1,
      "score": 0.9421,
      "payload": {
        "text": "AcadmyAI delivers zero-trust security, vector databases, and quantitative market telemetry...",
        "doc_id": "8e3fb2a1-4352-479c-b17d-948f219198ab",
        "chunk_index": 0
      }
    },
    {
      "id": 2,
      "score": 0.8874,
      "payload": {
        "text": "The suite includes RankAI for GEO marketing, SecureAI for zero-trust LLM guardrails, and VectorAI for vector storage.",
        "doc_id": "8e3fb2a1-4352-479c-b17d-948f219198ab",
        "chunk_index": 1
      }
    }
  ]
}

Developer Quota & Balance API

curl -X GET https://vector.acadmyai.com/v1/usage \
  -H "Authorization: Bearer sk-lvl1-your_api_key_here"

# pip install vectorai-sdk
from vectorai import VectorClient

client = VectorClient(api_key="sk-lvl1-your_api_key_here")

# Programmatically check quota, call counters, and days remaining
balance = client.get_usage()
print(f"Tier: {balance.tier} | Days Left: {balance.days_remaining}")
print(f"Chunks Stored: {balance.quota.total_chunks_stored} / {balance.quota.max_chunks_allowed}")
print(f"Chunks Remaining: {balance.chunks_remaining}")

const resp = await fetch("https://vector.acadmyai.com/v1/usage", {
  headers: { "Authorization": "Bearer sk-lvl1-your_api_key_here" }
});
const balance = await resp.json();
console.log(balance);

{
  "status": "success",
  "user_id": "usr_7894561230",
  "subscription": {
    "tier": "pro",
    "period": "monthly",
    "is_active": true,
    "expires_at": "2026-09-16T00:00:00Z",
    "days_remaining": 30
  },
  "quota": {
    "rate_limit_rpm": 120,
    "total_ingest_calls": 420,
    "total_search_calls": 1850,
    "total_chunks_stored": 12450,
    "max_chunks_allowed": 500000,
    "chunks_remaining": 487550
  },
  "active_profile": {
    "profile_name": "default",
    "provider": "huggingface",
    "embedding_model": "financial",
    "vector_db_provider": "memory",
    "default_collection": "enterprise_kb",
    "chunking_strategy": "recursive",
    "chunk_size": 512,
    "chunk_overlap": 64
  }
}

Pricing Plans & Throttling Limits API

curl -X GET https://vector.acadmyai.com/v1/billing/plans

System Health & SLA Endpoint

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-08-16T06:30:00Z"
}

🛡️ Security Model & BYOK Architecture

VectorAI enforces zero-trust data segregation across every layer of the API and vector infrastructure:

⚠️ HTTP Error Codes Matrix

VectorAI uses conventional HTTP response codes to indicate API success or failure. All error responses include an informative JSON detail message:

⏱️ Rate Limiting Rules

Rate limits are enforced using token bucket algorithms based on your active subscription plan: