API & Integration Guide

Welcome to the developer guide for the Verbatim AI API. This guide explains how to authenticate, how the API is
organized, and how to build a client that ingests documents and runs AI queries against them.

Verbatim AI is a Retrieval-Augmented Generation (RAG) platform. You upload documents into a corpus, the platform
vectorizes and indexes them, and you then ask questions in a session: the platform retrieves the most relevant
passages and asks a large language model to answer using them as context.

---

Where to find things

The OpenAPI spec is the source of truth for exact request/response schemas. This guide covers the concepts and
workflows that the spec alone does not explain.

---

Base URLs

All examples in this guide use relative paths (e.g. POST /v1/corpus/). Prefix them with the base URL of the
environment you target.

---

Core concepts

---

Table of contents

Read these in order if you are integrating for the first time:

1. API domains & conventions — the scope of each domain, base paths, pagination, error format,
   and an end-to-end client walkthrough.
2. Authentication — the two ways to authenticate (RSA JWT and access tokens), how scopes
   work, and which to use when.
3. RSA keys user guide — install and use scripts/build_keys.py to generate a key pair, publish
   the public key, and mint JWTs. Includes a language-agnostic recipe for signing JWTs in any stack.
4. Access keys — short-lived, scoped tokens for untrusted clients (browser JavaScript, the
   chatbot widget).
5. Security best practices — how to handle keys and tokens safely.

---

Conventions at a glance

• Versioning — public endpoints live under /v1/. Backoffice-only endpoints live under
  /_/v1/ and are not reachable with the credentials described in this guide.
• Authentication — every /v1/ request needs either an Authorization: Bearer <jwt>
  header or an X-Access-Token: <token> header. See Authentication.
• Pagination — list endpoints accept pageSize (default 25) and pageIndex
  (default 0, zero-based).
• IDs — all resource identifiers are UUIDv4 strings.
• Timestamps — ISO-8601 in UTC, e.g. 2026-04-23T04:06:51Z.
• Errors — non-2xx responses return a JSON body matching the Error schema (timestamp, status, error,
  message, path).

---

Quick start

1. Get an organization and register a public RSA key in the
   backoffice.

2. On your backend, mint an RSA-signed JWT — see the
   RSA keys guide.

3. Call the API with Authorization: Bearer <jwt>:

   Bash

   curl -H "Authorization: Bearer $JWT" \
        https://staging-api.verbatim-ai.com/v1/auth/whoami

4. Create a corpus, upload a document, open a session, and ask a question — the full sequence is
   in API domains & conventions.

5. For browser clients, don't ship your private key. Instead mint a short-lived
   access token from your backend and hand it to the frontend.