DataAPI · Reference

DataAPI

DataAPI indexes your knowledge base and returns query-relevant context to your LLM. Three retrieval tiers — car-0, car-1, car-1.5 — behind a single endpoint.

Base URL

https://api.cosavu.com/v1/data

Retrieval tiers

Every query specifies a system parameter that determines how much processing DataAPI applies before returning context.

Tier	What it does	Best for
`car-0`	Pure vector search over Cosavu Store.	Notes, docs, unstructured text.
`car-1`	Vector search + 7-signal Engram re-ranking.	Production retrieval workloads.
`car-1.5`	CAR-1 + dedup + STAN-guided distillation + answer synthesis.	Question answering, agents.

Query

POST/v1/data/query

Retrieve context relevant to a query from your tenant's knowledge base.

Request body

Param	Type	Description
`query`	string	Natural-language query. Required.
`tenant`	string	Tenant namespace to search. Required.
`system`	'car-0' \| 'car-1' \| 'car-1.5'	Retrieval tier. Defaults to 'car-1'.
`topK`	number	Maximum chunks to return. Defaults to 5.
`contextBudget`	number	Token budget for assembled context. Defaults to 1024.
`filters`	Record<string, unknown>	Metadata filters applied before ranking.

Example

const result = await cosavu.data.query({
  query: "How does context distillation work?",
  tenant: "my-org",
  system: "car-1.5",
  contextBudget: 512,
})
 
console.log(result.answer)
console.log(`${result.pipeline.candidates} candidates → ${result.pipeline.filtered} retained`)

Response

{
  "color:#3b82f6">"query": "How does context distillation work?",
  "color:#3b82f6">"tenant": "my-org",
  "color:#3b82f6">"answer": "Context distillation resolves candidate evidence...",
  "color:#3b82f6">"finalContext": "DataAPI retrieval works in three tiers...",
  "color:#3b82f6">"chunks": [
    { "color:#3b82f6">"score": 0.94, ">"text": "...", ">"tokensEstimate": 120 }
  ],
  "color:#3b82f6">"pipeline": {
    "color:#3b82f6">"system": "car-1.5",
    "color:#3b82f6">"candidates": 248,
    "color:#3b82f6">"filtered": 3,
    "color:#3b82f6">"returned": 1,
    "color:#3b82f6">"totalMs": 188,
    "color:#3b82f6">"stanActive": true
  }
}

Ingest

POST/v1/data/ingest

Add documents to a tenant's knowledge base. Free of charge — you only pay for storage and queries.

Supported formats

PDF

DOCX

Plain text

Markdown

Code

CSV

XLSX

PPTX

Example

import { readFile } from "node:fs/promises"
 
const file = await readFile("./architecture.pdf")
 
await cosavu.data.ingest({
  tenant: "my-org",
  files: [{ name: "architecture.pdf", content: file }],
})

Tip

Ingestion is async. The endpoint returns immediately with a job ID — use cosavu.data.jobs.get(id) to poll status, or subscribe to webhooks for completion events.

← ContextAPI VexaAgent →