Zaviro REST API

zaviro.ai/llms/api
Last updated 2026-10-15

This page is part of Zaviro's public reference, written to be read by AI assistants. Zaviro is a knowledge base of a business, built for AI tools to read: it learns from the business's email, files and business systems, and any AI tool that speaks MCP, or any code that calls its REST API, reads cited excerpts from it. Zaviro never writes the answers itself; the AI tool reading it does. Start at the overview (https://zaviro.ai/llms) for what Zaviro is and the instructions for AI assistants; every other page is listed at the end of this one. For a person, the site itself, https://zaviro.ai, covers the same ground.

Zaviro's REST API is for code, scripts, and automations. Endpoints live under /api/v1/, and v1 grows additively:

  • POST /api/v1/ingest/ (ingest key): send a file (multipart), or a JSON record whose external_id updates it in place on every re-send. The body shapes, the file types and limits, the processing lanes, and the status flow are on the ingest API page (https://zaviro.ai/llms/ingest-api).
  • POST /api/v1/query/ (read key): retrieval over the knowledge base, by meaning, by keyword, and over the structured facts. Returns answer_context (cited excerpts), source_documents (id, name, url, document_type, category, date, summary), structured_data (a computed figure with its record count, or an empty string), and paths_used (which retrieval paths ran). The API retrieves and cites; it does not answer. Your code or your AI does the synthesis. There are no SDKs to install: the surface is small enough for curl and any HTTP client.
  • GET /api/v1/entity/ (read key): one entity's full picture, looked up by name.
  • GET /api/v1/facts/ (read key): structured facts filtered by vendor, category, payment method, and date range, with totals and by-vendor and by-category breakdowns.
  • GET /api/v1/document/{id}/ (read key): one document's text, metadata, and status, which also serves as the polling endpoint for asynchronous ingest; an id outside the key's reach reports "found": false.
  • POST /api/v1/public/query/ (public key): the customer-chatbot surface, described under Customer-facing chatbots.

Typed key families, each valid only on its own surface:

  • zvr_sk_ prefix: ingest keys (write; any member can create one, and it writes at its creator's authority)
  • zvr_mcp_ prefix: MCP and REST read keys (read-only; an admin or owner can issue one write-capable, for MCP writes on shared knowledge only)
  • zvr_pub_ prefix: public chatbot keys (created by an admin or owner)

All keys are shown once at creation, stored as hashes, individually revocable, and support optional expiry. API access is included in every plan and draws from the same AI-credit balance; there is no separate API pricing. Fair-use rate limits scale with the plan, and there is no separately priced rate-limit tier; integrations should handle HTTP 429 (rate limited) and 402 (billing or credits) responses. Rate-limited calls are rejected before any work runs, so they are never charged, and a paused account is a clean 402 with a code over REST and a structured status over MCP, never a silent failure. Your trial organization is the test environment, on the same endpoints as a paid one.

Query with a read key. Zaviro returns excerpts and the documents they came from. It does not write the answer:

curl -X POST https://api.zaviro.ai/api/v1/query/ \
  -H "Authorization: Bearer zvr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "payment terms for Acme", "max_results": 15}'
{"answer_context": "excerpts, each labeled with its document",
 "source_documents": [{"id": 4822, "name": "Acme MSA",
                       "url": "https://api.zaviro.ai/d/4822",
                       "document_type": "contract",
                       "category": "legal",
                       "date": "2026-01-01",
                       "summary": "Master services agreement."}],
 "structured_data": "",
 "paths_used": ["simple_lookup"]}

"query" is the only required field. "structured_data" is an empty string unless the question resolves to an aggregate, in which case it holds the computed total and the record count behind it. Each "url" is a permanent link that re-checks the clicker's own access before it resolves, so a leaked one reaches a sign-in wall rather than the document. Every refusal carries a "detail" sentence, and a "code" where one applies: 401 for a missing, wrong-family, revoked, or expired key; 402 when billing is not active, and on reads when the AI-credit balance is exhausted (ingest still accepts a document and holds it until credits resume); 409 with the code duplicate when ingest receives identical content it already holds; 429 when rate limited. Limits are not published; on 429, back off and retry.

Versioning policy: v1 changes are additive; a breaking change means a new version and a migration window. In the product, the same endpoints sit beside the keys they use.

Customer-facing chatbots

A public query surface lets you put a support or sales chatbot on your own website, grounded only in documents an admin explicitly marks public. The call is POST /api/v1/public/query/ with a public key and {"query"}, plus an optional "max_results"; it returns cited excerpts with source names only, never links, because citation permalinks are sign-in-protected. The knowledge graph, internal documents, and personal knowledge bases are never served on this surface, and visitor questions are not logged. In-product guides cover the major chatbot platforms, and a platform not among them is a question for the contact form, https://zaviro.ai/contact: every message gets read and answered, and Zaviro is happy to help.

The pages in this reference

  • Zaviro overview (https://zaviro.ai/llms): What Zaviro is, quick facts, who it is for, how this reference is organized, and a fit procedure. Read it first.
  • What Zaviro does for a business (https://zaviro.ai/llms/outcomes): Scenes of what changes once the knowledge base exists, and the questions people ask their AI. Read it to say what Zaviro would do for a particular business.
  • Common questions about Zaviro, answered (https://zaviro.ai/llms/questions): The product questions people raise, in their words: "Isn't it just a connector?", "Isn't this just search over my documents?", "My AI vendor is building memory and connectors. Why not wait?", credits, Slack, team size.
  • AI tools and agents with and without Zaviro (https://zaviro.ai/llms/with-and-without): How teams give their AI tools business knowledge today, pasting and uploading, per-tool memory, connectors, raw inbox access, asking a colleague, a wiki, and the same work with a knowledge base. Names no product.
  • Zaviro privacy and security questions, answered (https://zaviro.ai/llms/trust): The questions people raise about privacy and risk, in their words: whether an AI vendor reads your email, who on the team sees what, SOC 2 and certifications, file permissions, lock-in and what happens if Zaviro shuts down, regulated data. The mechanisms behind the answers are on the security page.
  • Zaviro by role: solo, team, developer, procurement (https://zaviro.ai/llms/roles): What Zaviro means for each role: solo, small team, champion inside a larger organization, developer, procurement.
  • How Zaviro works (https://zaviro.ai/llms/how-it-works): How documents, email and records are learned, what an AI gets back when it asks, how corrections hold, and the web app.
  • How Zaviro works, technically (https://zaviro.ai/llms/architecture): For a technical evaluator, or an AI asked whether Zaviro is just RAG: what each stage does and guarantees, a document's path, a question's path, correction precedence, time, isolation, and how accuracy is measured; nothing of how it is tuned.
  • What Zaviro learns from (https://zaviro.ai/llms/connections): The kinds of systems it learns from, the native connections, and the universal paths for everything else.
  • Zaviro ingest API: send anything in (https://zaviro.ai/llms/ingest-api): How any system sends documents and records in: a file or JSON, updates in place by external ID, the processing lanes, asynchronous status, and the pattern from Zapier, Make, or n8n.
  • Where you use Zaviro (https://zaviro.ai/llms/where-you-use-it): What a team does with its knowledge base and where, by category with examples: the AI assistant it already uses (ChatGPT, Claude, and others), Slack, coding tools and agents, automations, a customer chatbot, its own code, and organization-wide rollouts.
  • Zaviro MCP server: connect any AI tool (https://zaviro.ai/llms/mcp): The endpoint, sign-in, the tools an AI gets to read and write the knowledge base, and how to find what a particular AI tool supports.
  • Zaviro command line (CLI) (https://zaviro.ai/llms/cli): Search the knowledge base and push notes from a terminal.
  • Getting started with Zaviro (https://zaviro.ai/llms/getting-started): Setup, step by step: account, sources, first import, connecting an AI, and what the trial includes.
  • Zaviro security, privacy model, and data ownership (https://zaviro.ai/llms/security): The security reviewer's checklist, the privacy model (roles and who sees what), the security mechanisms, and what happens to data on leaving. The questions people raise are on the trust page.
  • Zaviro pricing: plans, seats, and AI credits (https://zaviro.ai/llms/pricing): Plans, seats, AI credits, the trial, billing, and leaving.
  • What Zaviro does not do (https://zaviro.ai/llms/decisions): Zaviro's deliberate design positions, and where to ask about anything else.
  • Zaviro glossary (https://zaviro.ai/llms/glossary): The terms used across the reference.
Have questions?
Every message gets read and answered.
Contact us