REST API

REST API

All endpoints are served under http://<host>:6340/v1. Authenticated requests pass a JWT as Authorization: Bearer <token> (obtain one via POST /v1/auth/login). The full machine-readable spec lives at documentation/openapi.yaml in the repository.

Collections

MethodPathDescription
POST/v1/collectionsCreate a collection (supports seed_records for atomic create-and-load, use_log_primary for on-disk records, rls_owner_field for row-level security; vector fields take index: hnsw · diskann · ivfpq · flat · rabitq · rabitq_rerank · hnsw_rabitq · rabitq_ext_rerank · sq4 · sq8)
POST/v1/collections with externalRegister a read-in-place external Parquet collection. fields must be []; schema and vector dimension are inferred from the Parquet footer and validated at registration. Requires Admin (403 otherwise); read-only thereafter — 18 mutating endpoints return 405
GET/v1/collectionsList collections
GET/v1/collections/{name}Get a collection's schema and stats
DELETE/v1/collections/{name}Drop a collection
POST/v1/collections/{name}/reindexRe-chunk / re-embed into a sibling and atomically swap the alias
MethodPathDescription
POST/v1/collections/{name}/insertInsert records (flat field→value maps)
POST/v1/collections/{name}/embed-insertInsert with server-side auto-embedding (auto_embed map)
POST/v1/collections/{name}/ingest-mediaMultipart upload-and-embed for image/audio/video (-F file=@…) — infers modality, embeds, stores the blob, inserts; see Multimodal
GET/v1/collections/{name}/recordsList records (paginated; supports ?at=<ts> snapshot reads)
GET/v1/collections/{name}/records/{id}Fetch one record
POST/v1/collections/{name}/searchSearch: vector, bm25, sparse_vector, hybrid, or multi_vector queries + filter, rerank, explain, ?at=<ts>
POST/v1/collections/{name}/sealExplicit seal/flush so declared index types build on sealed segments (also VEDA_SEAL_THRESHOLD)
GET/v1/collections/{name}/coverageField coverage statistics

Search request shape

json
{
  "query": {
    "vector": { "field": "embedding", "values": [0.15, 0.22] }
  },
  "limit": 10,
  "filter": "category = 'electronics' AND price < 500",
  "rerank": false,
  "explain": true
}

See Search & fusion for multi_vector fusion, hybrid queries, and snapshot reads.

Analytics

Read-only OLAP-style aggregations over the columnar store. All three honor the filter DSL (including JSON-path filters) and row-level security.

MethodPathDescription
GET/v1/collections/{name}/aggregate?field=&metric={count|sum|avg|min|max}&group_by=&filter= — scalar metric, optionally bucketed per group
GET/v1/collections/{name}/histogram?field=&bins=&filter= — equal-width numeric histogram (default 10 bins)
GET/v1/collections/{name}/field-stats?field=&filter= — total/null counts, cardinality, numeric or string-length summaries
bash
# Average price per category, electronics under $500 only
curl "http://localhost:6340/v1/collections/products/aggregate?field=price&metric=avg&group_by=category&filter=price%20%3C%20500"

Note: group_by on a text field returns each group's key verbatim, so this endpoint can return the text of guardrail-flagged records. That is deliberate for the raw data API — like /search, it annotates and never drops, so recall measurement stays intact. The aggregate tool that agents and MCP clients call does skip hostile-flagged records; see Retrieval guardrails below.

Scheduled jobs

Admin-only cron scheduler. A job is a cron expression plus a typed kind — ttl_sweep, reindex, compact, or evaluate, each scoped to a collection — deliberately not arbitrary code. Jobs persist in the data directory and reload on restart. (ttl_sweep is fully wired today; the other kinds are registered hooks.)

MethodPathDescription
POST/v1/admin/jobsRegister or overwrite a job (400 on an invalid cron expression)
GET/v1/admin/jobsList registered jobs
DELETE/v1/admin/jobs/{name}Remove a job
bash
# Sweep expired records from the cache collection every 5 minutes
curl -X POST http://localhost:6340/v1/admin/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "cache-ttl-sweep",
    "cron": "0 */5 * * * *",
    "kind": {"kind": "ttl_sweep", "collection": "cache"}
  }'

cron accepts a 5-field Unix expression (0 3 * * * = 03:00 daily) as well as the 6- and 7-field forms with a leading seconds field. kind is an internally tagged enum, so it nests as {"kind": {"kind": "...", ...}} — the same shape SLO kind and synthetic-probe kind use.

Documents

MethodPathDescription
POST/v1/collections/{name}/process-documentOCR → chunk → embed → insert one file (multipart file). Text chunks and extracted images fill the same dense vector fields, so a collection that ingests images needs a multimodal model; a schema whose vector field no image can fill is rejected with 409 INCOMPATIBLE_SCHEMA before anything is written — see Document pipeline
POST/v1/collections/{name}/process-documentsBatch variant (multipart files)
POST/v1/collections/{name}/ingest-urlCrawl a URL → clean markdown → chunk → embed → insert ({ url|urls, deep_crawl?, max_pages?, chunker?, ttl_secs? }); see Web Connectors; 503 if crawl4ai unconfigured
POST/v1/chunk/previewPreview how text would be chunked under a strategy

Connectors

Admin-only web data-source connectors (declarative, persisted, re-runnable). See Web Connectors.

MethodPathDescription
GET/POST/v1/admin/connectorsList / create a connector ({ kind: "web", name, config, enabled }; id server-assigned if omitted)
GET/PUT/DELETE/v1/admin/connectors/{id}Read / update / delete a connector
POST/v1/admin/connectors/{id}/runRun now — crawl the connector's URLs into its target collection (503 if crawl4ai unconfigured)

Embedding & models

MethodPathDescription
POST/v1/embedEmbed text / image_b64 / audio_b64 / video_b64 directly → {model, modality, dimension, values, elapsed_ms}; optional model override (see Multimodal)
POST/v1/llm/completeLLM completion passthrough (used by Niriksha features)
POST/v1/routeModality routing helper

Agents, tools & MCP

The agentic layer and MCP surface. See Agents & MCP for the full guide.

Agents

MethodPathDescription
GET/v1/agentsList agents
POST/v1/agentsCreate or upsert an agent (empty id → generated)
GET/PUT/DELETE/v1/agents/{id}Manage one agent
POST/v1/agents/{id}/converseRun a tool-calling turn — body { input, conversation_id?, attachments? }; returns metrics + citations + grounding; 503 without an LLM, 404 for an unknown non-default agent
POST/v1/agents/{id}/converse/streamStreaming converse over SSE — reasoning/tool/answer deltas then a done frame with metrics + citations + grounding; 503 no LLM

Tools

MethodPathDescription
GET/POST/v1/agent-toolsList / create custom tools
GET/PUT/DELETE/v1/agent-tools/{id}Manage one custom tool
GET/v1/agent-tools/catalogBuilt-in tool specs (id, description, inputSchema, annotations)
POST/v1/agent-tools/{id}/executeRun one tool directly (invalid→400, not-found→404, internal→500)

Conversations

MethodPathDescription
GET/v1/conversationsList conversations
GET/DELETE/v1/conversations/{id}Fetch / delete one conversation
POST/v1/conversations/{id}/feedbackThumbs feedback { rating: up|down, note? } (see LLM Observability)

Eval harness — see RAG & AIOps Intelligence.

MethodPathDescription
GET/POST/v1/eval-setsList / create-or-overwrite eval sets (id server-assigned if omitted)
GET/DELETE/v1/eval-sets/{id}Get / delete an eval set
POST/v1/eval-sets/{id}/runRun → per-case + aggregate recall@k / faithfulness / answer-relevancy / pass_rate; 503 no LLM
GET/v1/eval-sets/{id}/runsList past runs
POST/v1/eval-sets/{id}/cases/from-conversationGraduate a production conversation into a regression case

Auto-tuning — see RAG Auto-Tuning.

MethodPathDescription
POST/v1/collections/{name}/eval-sets/generateGenerate a labeled eval set from the collection's own documents ({ name?, num_cases })
GET/v1/collections/{name}/eval-set-size-recommendationCorpus-aware { recommended, max, chunk_count, document_count }
GET/PUT/v1/collections/{name}/auto-optimizationPer-collection opt-in: regenerate + re-tune on every ingest ({ enabled, target_questions?, mode })
POST/v1/collections/{name}/tuning-campaignsRun a nested config search → Pareto front ({ eval_set_id, max_trials?, num_bases?, mode? })
POST/v1/tuning-campaigns/{campaign_id}/trials/{trial_id}/applyApply a trial — tier-1 instant/reversible; tier-2/3 via /reindex + alias swap

mode is "Quality" or "Performance" — capitalized exactly, on both endpoints. Any other spelling ("quality") is rejected with 422.

MCP & A2A

MethodPathDescription
POST/v1/mcpJSON-RPC 2.0 MCP server (protocol 2025-06-18): initialize, tools/list, tools/call, ping. GET → 405
GET/v1/a2a/{agent_id}/cardA2A AgentCard (skills derived from the agent's tools)
POST/v1/a2a/{agent_id}A2A JSON-RPC message/send — one-shot agent turn; 503 without an LLM

Transactions

Percolator-style snapshot-isolation transactions:

MethodPathDescription
POST/v1/txnBegin / commit / abort transactional operations

Write skew is allowed (snapshot isolation); lost updates are prevented; read-only transactions are consistent.

Auth & saved objects

MethodPathDescription
POST/v1/auth/loginExchange username/password for a JWT (Argon2id verification)
GET/v1/saved_objectsList saved objects used by the Niriksha dashboard
PUT/DELETE/v1/saved_objects/{id}Upsert (create-or-replace) / delete one saved object. There is no POST collection route and no GET by id — create with PUT on the id you choose, and read via the list

Admin

MethodPathDescription
GET/v1/admin/healthLiveness — always 200, with per-dependency checks
GET/v1/admin/readinessReadiness — 503 when unhealthy
GET/v1/admin/metricsPrometheus text-format metrics
GET/v1/admin/nodesNode list; mode reports "single" or "raft"
GET/PUT/v1/admin/region_topologyCross-region replication topology (writes require Raft)
POST/v1/admin/region_topology/promotePromote a replica region (Raft only)
GET/POST/v1/admin/replica/safe_tsReplica read watermark
POST/v1/admin/cluster/join · DELETE /v1/admin/cluster/nodes/{id}Raft membership changes
POST/v1/admin/collections/{name}/mvcc_checkpointAtomic MVCC snapshot + WAL truncate
POST/v1/admin/collections/{name}/rescan-guardrailsRe-screen every record and persist the retrieval-guardrail verdict (_guardrail_flagged/_guardrail_score/_guardrail_category/_indexed_at); rebuilds through /reindex and atomically swaps the alias; returns { scanned, flagged, skipped }. Known limitation: superseded siblings from repeated /rescan-guardrails or /reindex calls are never dropped, so repeated rescans grow storage

Endpoints marked Raft-only return 503 in single-node mode — see Cluster modes.

Retrieval guardrails

The threat model, the calibration numbers and the coverage gaps are covered in Retrieval guardrails.

Ingest screens each chunk's text embedding and stamps the four reserved fields above. On every LLM-facing path (/converse, /converse/stream, MCP tools/call, /agent-tools/{id}/execute, /a2a/{agent_id}), the response carries a retrieval_guard report — { kept, dropped, unscreened, skipped, flagged_not_dropped, withheld_records, dropped_chunks: [{ id, category, score }] } — and get_record applies the same policy to a directly-fetched record (withholding it if dropped). On /converse and the /converse/stream done frame the report is at the top level, rolled up across every retrieving tool call in the turn; a turn that retrieved nothing omits the field entirely rather than reporting zeros. POST /v1/collections/{name}/search instead annotates each hit with _guardrail_class and never drops.

The aggregate tool skips hostile-flagged records in its record walk and reports retrieval_guard.withheld_records, because group_by on a text field returns each group's key verbatim and would otherwise emit the withheld text. That count is per-query — the skip runs after the filter, so it reports what this aggregation excluded, not how many hostile records the collection holds — and it rolls up into the turn-level report like every other count, so an aggregate-only turn still reports retrieval_guard. The raw GET /v1/collections/{name}/aggregate endpoint is unaffected and still counts every record — like /search, the data API annotates and never drops, so recall measurement stays intact.

Kill switch. VEDA_RETRIEVAL_GUARD=off (also 0/false/no/disabled) degrades every LLM-facing path to annotate-only: hits are still classified and counted (flagged_not_dropped reports what would have been dropped), nothing is removed. Unset — or set to anything else — enforces. It is read per tool dispatch, so it takes effect without a restart. Enforcement is otherwise unconditional and is not gated on an agent's guardrails flag, which governs input/output safety guardrails only.

Dropping is category-aware. PromptInjection, Jailbreak, Unsafe, and IndirectInjection are hostile — those chunks are dropped before the LLM sees them and counted in dropped / dropped_chunks. Pii (an email, phone number, etc. detected in the chunk text) is detected and reported but passed through unchanged, counted in flagged_not_dropped instead: this feature targets OWASP's injection/poisoning/temporal vectors, and silently stripping a genuine contact detail out of an answer to "who do I contact about X" was found to be a worse failure than the threats it targets. An unrecognised or missing category on a flagged chunk is treated as hostile and dropped — fails closed, since an unfamiliar category is more likely a new threat than a benign one.

Known limitations

  • Chunks indexed before this feature carry no verdict, are reported as unscreened, and are passed through; run the re-scan to close that gap.
  • Plain POST /v1/collections/{name}/insert is never screened. Screening runs against a text embedding Veda computed itself, so it only happens on process-document, ingest-url and embed-insert. /insert takes client-supplied vectors, so every record it writes is stamped skipped — this includes the Python SDK's normal client-side-embedding path. Unlike the pre-feature case above, one upgrade-time re-scan does not close it: it recurs with every /insert, so a corpus ingested that way needs the re-scan run on a cadence.
  • Temporal conflict detection is active on the filter_query tool and inert on search. It compares hits' stored vectors, and search deliberately omits vector fields from hydrated hits (hydrating them would inflate every LLM-facing payload). Staleness and expiry work on both.

Ops Advisor (Insights)

Admin-only automated-operations surface. See Ops Advisor for the full guide.

MethodPathDescription
GET/v1/admin/insightsOpen events (?severity=, ?scope= filters), severity-sorted
GET/v1/admin/insights/historyClosed events (bounded history)
GET/v1/admin/insights/rulesRule catalog with effective config per rule
PUT/v1/admin/insights/rules/{id}Tune enabled / muted / severity_override / thresholds / auto_remediate
GET/PUT/v1/admin/insights/channelsAlert-channel config (secrets write-only on GET)
POST/v1/admin/insights/runForce one evaluation tick → { opened, closed }
POST/v1/admin/insights/{event_id}/ackAcknowledge an open event
POST/v1/admin/insights/{event_id}/triageAI triage of an event — grounded explanation + tool trace, now enriched with the RCA bundle (404 unknown, 503 no LLM)
GET/v1/admin/insights/{event_id}/rcaCross-signal root-cause bundle — logs + queries + traces + resources + incident
GET/v1/admin/incidentsSemantic incident clusters — with draft (proactive RCA), is_novel / novelty_score, and a noise_reduction summary
GET/v1/admin/forecastCapacity forecasts — disk-full / memory-exhaustion / recall-decay ETAs
GET/v1/admin/change-pointsChange-point detections — sustained level shifts / trend breaks (warm-up ≥20 pts, 1.5σ)
GET/v1/admin/log-rate-analysisSemantic spike attribution — meaning-clusters driving a log-rate spike (?window_secs=&baseline_secs=&min_level=)
GET/v1/admin/resourcesLocal node's latest resource snapshot — disk, CPU, load, fds, memory, RSS (see Node Resource Signals); always 200, fields nullable

Service Reliability (SLOs & synthetics)

Admin-only SLO and synthetic-probe surface. See Service Reliability for the full guide.

MethodPathDescription
GET/POST/v1/admin/slosList SLO defs / create-or-overwrite (POST needs an explicit id)
GET/PUT/DELETE/v1/admin/slos/{id}Get / update / delete one SLO (404 if missing)
GET/v1/admin/slos/{id}/statusCurrent SLI / error-budget / burn-rate status
GET/POST/v1/admin/syntheticsList probe defs / create-or-overwrite
GET/PUT/DELETE/v1/admin/synthetics/{id}Get / update / delete one probe
GET/v1/admin/synthetics/{id}/resultsRecent per-probe results + summary

APM & performance

Admin-only application-performance surface. See APM & Performance Observability for the full guide.

MethodPathDescription
GET/v1/admin/correlationsSlow-query / error correlation, bucketed and ranked worst-first
GET/v1/admin/pprofOn-demand CPU profile (?seconds=, ?frequency=, ?format=flamegraph|pprof); profiling build; 409 if running
GET/v1/admin/depmapDeclarative service dependency graph (9 nodes / 8 edges)
GET/v1/admin/index-advisorPer-collection index type / params / p95 / recall + recommendations + open events

POST /v1/agents/{id}/converse and POST /v1/admin/insights/{event_id}/triage also return metrics (RunMetrics: timings + token counts).

Logs (Log Insights)

Captured-log and log-ingest surface. See Log Insights for the full guide.

MethodPathDescription
GET/v1/admin/logsRecent captured logs (?level=, ?q=, ?limit=) — admin-only
GET/v1/admin/logs/categoriesSemantic log categories — admin-only
GET/v1/admin/slow-queriesSlowest recent queries (?collection=, ?limit=) — admin-only
POST/v1/collections/{name}/ingest-logsParse raw log lines into records ({ lines, default_level?, ttl_secs? }); same auth as /insert

LLM Observability

Admin-only LLM trace surface. See LLM Observability for the full guide.

MethodPathDescription
GET/v1/admin/llm-tracesSemantic search over the _llm_traces store (?q=&limit=)
GET/v1/admin/llm-traces/clustersFailure clustering — recurring failure modes (category, representative, count)