> For the complete documentation index, see [llms.txt](https://verbatim-ai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://verbatim-ai.gitbook.io/docs/integration/home.md).
# 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
| Resource | Link |
| ----------------------------------- | --------------------------------------------------- |
| API docs | |
| API Status | |
| Swagger playground | |
| OpenAPI specification (JSON) | |
| Backoffice user guide | |
| Managing API keys in the backoffice | |
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
| Environment | Base URL |
| ----------- | ------------------------------------- |
| Staging | `https://staging-api.verbatim-ai.com` |
| Production | `https://api.verbatim-ai.com` |
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
| Concept | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Organization** | The top-level tenant. Every token is bound to exactly one organization (the `oid` claim). All data is scoped to it. |
| **Corpus** | A knowledge base. Holds documents and sessions, and is the unit every other resource is scoped to. |
| **Document** | A file ingested into a corpus (PDF, DOCX, HTML…). Ingestion is asynchronous: convert → summarize → chunk → embed. |
| **Session** | A conversation thread bound to one or more corpora. How its queries are answered is decided per query by the agent. |
| **Post** | A single user query or system answer inside a session. Answers carry *attachments* — the document chunks used as context. |
***
## Table of contents
Read these in order if you are integrating for the first time:
1. [**API domains & conventions**](/docs/integration/api-domains.md) — the scope of each domain, base paths, pagination, error format, and an end-to-end client walkthrough.
2. [**Authentication**](/docs/integration/authentication.md) — the two ways to authenticate (RSA JWT and access tokens), how scopes work, and which to use when.
3. [**RSA keys user guide**](/docs/integration/rsa-keys.md) — 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**](/docs/integration/access-keys.md) — short-lived, scoped tokens for untrusted clients (browser JavaScript, the chatbot widget).
5. [**Security best practices**](/docs/integration/security.md) — 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 ` header or an `X-Access-Token: ` header. See [Authentication](/docs/integration/authentication.md).
* **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](https://verbatim-ai.gitbook.io/docs/api-keys).
2. On your **backend**, mint an RSA-signed JWT — see the [RSA keys guide](/docs/integration/rsa-keys.md).
3. Call the API with `Authorization: Bearer `:
```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](/docs/integration/api-domains.md#end-to-end-client-walkthrough).
5. For **browser** clients, don't ship your private key. Instead mint a short-lived [access token](/docs/integration/access-keys.md) from your backend and hand it to the frontend.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://verbatim-ai.gitbook.io/docs/integration/home.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.