# VectorAI API Specification for LLMs & AI Agents
> VectorAI (v2.0) is an enterprise zero-trust vector database engine, real-time multi-modal chunking gateway, and decentralized BYOK model orchestration engine.
> Canonical Base URL: https://vector.acadmyai.com
> Official SDKs: PyPI `vectorai-sdk` (v1.1.0) | NPM `@vectorai-sdk/sdk` (v1.0.1)

## Authentication
Every API request requires a Bearer token in the `Authorization` header:
`Authorization: Bearer <vec_live_... | sk-lvl1-...>`
API keys are scoped per integration profile (e.g. `launchai`, `tradeai`, `grokbot`). Keys can be generated in the console at `https://vector.acadmyai.com/console/profiles`.

---

## Core Endpoints

### 1. Ingest Documents or Text Chunks
`POST /v1/ingest`
Ingests text into the specified collection, generates dense vector embeddings via the active profile's configured model (Gemini, OpenAI, Cohere, HuggingFace), runs Presidio PII pseudonymization, and indexes vectors into PostgreSQL pgvector, Qdrant, or In-Memory RAM.

**Request JSON Body:**
```json
{
  "text": "Enterprise SSO supports Okta, Google Workspace, and Azure AD with SCIM.",
  "collection_name": "sales_vault",
  "metadata": {
    "source": "knowledge_base",
    "channel_id": "slack_general",
    "author": "grokbot"
  },
  "pii_redaction": true,
  "threat_action": "sanitize"
}
```
- `text` (string, required): Raw text content.
- `collection_name` (string, optional, defaults to profile default): Destination collection namespace.
- `metadata` (object, optional): Key-value payload for filtering and ACL checks.
- `pii_redaction` (boolean, optional, default `true`): Masks Aadhaar, PAN, SSNs, credit cards, emails.
- `threat_action` (string, optional, enum: `block` | `sanitize` | `monitor`, default `sanitize`): Mitigation action if prompt injection or jailbreak payload is detected.

**Response JSON (200 OK):**
```json
{
  "status": "success",
  "document_id": "doc_8f9c1b3e",
  "collection_name": "sales_vault",
  "chunks_stored": 1,
  "pii_redacted": false,
  "threat_detected": false
}
```

---

### 2. Semantic Similarity Search
`POST /v1/search`
Generates an embedding for the search query and performs dense cosine similarity search over vector indices in < 10ms.

**Request JSON Body:**
```json
{
  "query": "How do we configure SAML SSO?",
  "collection_name": "sales_vault",
  "top_k": 3,
  "filter": {
    "source": { "$eq": "knowledge_base" }
  },
  "threat_action": "sanitize"
}
```
- `query` (string, required): Natural language query string.
- `collection_name` (string, optional): Target collection.
- `top_k` (integer, optional, default `5`, max `100`): Number of most relevant chunks to return.
- `filter` (object, optional): MongoDB-style metadata filter dictionary (`$eq`, `$in`, `$gte`, `$lte`, `$ne`).
- `threat_action` (string, optional): Real-time prompt injection defense on the search query.

**Response JSON (200 OK):**
```json
{
  "status": "success",
  "query": "How do we configure SAML SSO?",
  "results": [
    {
      "id": "chunk_01",
      "score": 0.894,
      "text": "Enterprise SSO supports Okta, Google Workspace, and Azure AD with SCIM.",
      "metadata": {
        "source": "knowledge_base",
        "channel_id": "slack_general"
      }
    }
  ],
  "latency_ms": 7.4
}
```

---

### 3. Asynchronous Batch Ingestion Jobs
`POST /v1/jobs/batch-ingest`
Submits bulk document payloads for asynchronous multi-worker background ingestion.

**Request Body:**
```json
{
  "collection_name": "bulk_docs",
  "documents": [
    { "text": "Document chunk 1...", "metadata": { "id": 1 } },
    { "text": "Document chunk 2...", "metadata": { "id": 2 } }
  ]
}
```
**Response JSON (202 Accepted):**
```json
{
  "job_id": "job_94a3b8e1",
  "status": "processing",
  "total_items": 2
}
```

Poll Status: `GET /v1/jobs/{job_id}`
Returns `{ "status": "completed", "processed_items": 2, "failed_items": 0 }`.

---

### 4. Health & Latency Probe
`GET /v1/health`
Returns gateway health and active driver status.

---

## Code Examples

### Python SDK (`vectorai-sdk`)
```python
from vectorai import VectorAI

client = VectorAI(api_key="vec_live_YOUR_API_KEY", base_url="https://vector.acadmyai.com")

# 1. Ingest
client.ingest(
    text="Quarterly guidance: FY26 Q3 revenue projected at $45M.",
    collection_name="finance_vault",
    metadata={"quarter": "Q3-2026", "audience": "analysts"}
)

# 2. Search
results = client.search(
    query="What is the revenue target for Q3?",
    collection_name="finance_vault",
    top_k=3
)
for hit in results.results:
    print(f"[{hit.score:.3f}] {hit.payload.get('text')}")
```

### TypeScript SDK (`@vectorai-sdk/sdk` v1.0.1)
```typescript
import { VectorAIClient } from "@vectorai-sdk/sdk";

const client = new VectorAIClient({
  apiKey: "vec_live_YOUR_API_KEY",
  baseUrl: "https://vector.acadmyai.com",
});

async function main() {
  // 1. Ingest document chunk
  await client.ingest({
    text: "Autonomous SDR playbook: Handle objections with SOC2 compliance proof.",
    collection_name: "sdr_playbook",
    metadata: { category: "security" },
    pii_redaction: true,
    threat_action: "sanitize"
  });

  // 2. Search collection
  const response = await client.search({
    query: "How to handle security objection?",
    collection_name: "sdr_playbook",
    top_k: 2,
    threat_action: "sanitize"
  });
  console.log("Hits:", response.results);

  // 3. List Collections
  const collections = await client.listCollections();
  console.log("Collections:", collections);
}
main();
```

### Raw cURL
```bash
# Ingest
curl -X POST https://vector.acadmyai.com/v1/ingest \
  -H "Authorization: Bearer vec_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "collection_name": "demo"}'

# Search
curl -X POST https://vector.acadmyai.com/v1/search \
  -H "Authorization: Bearer vec_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "collection_name": "demo", "top_k": 3}'
```