> 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/clients.md). # Client libraries, demos and tools Everything we publish for API integrators lives in one place — the **Verbatim AI GitHub organization**: > You never *need* any of it: the API is plain HTTPS + JSON and `curl` works fine (see the [API & Integration Guide](/docs/integration/home.md)). These repositories exist to remove the boilerplate — typed models, authentication wiring, and a couple of ready-made tools. *** ## At a glance | Repository | Language | What it is | | ----------------------------------------------------------------------------------- | ---------- | ----------------------------------------- | | [`python-client`](https://github.com/verbatim-ai/python-client) | Python | Generated SDK for the REST API | | [`typescript-node-client`](https://github.com/verbatim-ai/typescript-node-client) | TypeScript | Generated SDK for the REST API | | [`java-spring-rest-client`](https://github.com/verbatim-ai/java-spring-rest-client) | Java | Generated SDK (Spring `RestTemplate`) | | [`java-resteasy-client`](https://github.com/verbatim-ai/java-resteasy-client) | Java | Generated SDK (JAX-RS / RESTEasy) | | [`python-token-builder`](https://github.com/verbatim-ai/python-token-builder) | Python | Generate RSA key pairs and mint JWTs | | [`file-directory-sync`](https://github.com/verbatim-ai/file-directory-sync) | Python | Sync a local directory tree into a corpus | | [`client-demo`](https://github.com/verbatim-ai/client-demo) | Mixed | End-to-end REST client examples | All repositories are public. No registry publication yet — install straight from Git (see each section below). *** ## API clients The four SDKs are **generated from the OpenAPI specification**, so they always expose the same surface: `Auth`, `Corpus`, `Document`, `Session`, `Post` and `Usage` APIs, plus typed models for every request and response. They are regenerated whenever the spec changes — do not hand-edit them, your changes will be overwritten on the next build. All four support the two authentication schemes described in [Authentication](/docs/integration/authentication.md): * **JWT Bearer** — `Authorization: Bearer `, for server-to-server calls. See [RSA Keys](/docs/integration/rsa-keys.md). * **Access token** — `X-Access-Token: `, short-lived, for browsers and untrusted clients. See [Access Keys](/docs/integration/access-keys.md). ### Python — `python-client` Requires **Python 3.10+**. Package name: `verbatim_client`. ```shell pip install git+https://github.com/verbatim-ai/python-client.git ``` ```python import verbatim_client configuration = verbatim_client.Configuration( host="https://api.verbatim-ai.com", access_token="", ) with verbatim_client.ApiClient(configuration) as api_client: corpus_api = verbatim_client.CorpusApi(api_client) corpora = corpus_api.list_corpus() ``` ### TypeScript / Node — `typescript-node-client` Package name: `verbatim_client`. Clone, then: ```shell npm install npm run build ``` ```ts import { CorpusApi } from "verbatim_client"; const api = new CorpusApi("https://api.verbatim-ai.com"); api.setApiKey(/* JWT bearer */ ""); ``` ### Java (Spring) — `java-spring-rest-client` Built on Spring's `RestTemplate`. Requires **Java 8+** and Maven or Gradle. ```xml com.verbatim.client spring-rest 1.0.0 ``` ```shell mvn clean install # install to your local ~/.m2 repository ``` ```java ApiClient client = Configuration.getDefaultApiClient(); client.setBasePath("https://api.verbatim-ai.com"); HttpBearerAuth jwt = (HttpBearerAuth) client.getAuthentication("JWT"); jwt.setBearerToken(""); CorpusApi api = new CorpusApi(client); ``` Packages: `com.verbatim.client.springrest.{api,invoker,models}`. ### Java (RESTEasy) — `java-resteasy-client` Same API, JAX-RS / RESTEasy transport — use this one when you are not in a Spring application. ```xml com.verbatim.client resteasy 1.0.0 ``` Packages: `com.verbatim.client.resteasy.{api,invoker,models}`. Setup is identical to the Spring client above. *** ## Tools ### `python-token-builder` — keys and tokens The companion to the [RSA Keys User Guide](/docs/integration/rsa-keys.md). A dependency-free helper (Python 3.10+ and `openssl` on your `PATH`) that generates an RSA-4096 key pair and mints RS512 JWTs: ```shell # 1. generate a key pair — register the .pub file in the backoffice python key-builder/main.py --gen-keys --key-name staging # 2. mint a token with the key id the backoffice gave you python key-builder/main.py \ --key-name staging \ --key-id \ --org-id ``` The JWT goes to **stdout** and diagnostics to **stderr**, so it pipes cleanly into `curl` or `pbcopy`. Use it for testing and bootstrapping; in production, sign tokens inside your own backend — [Part B of the RSA Keys guide](/docs/integration/rsa-keys.md) shows the equivalent in Node.js, Python and Java. ### `file-directory-sync` — keep a corpus in step with a folder Mirrors a local directory tree into a corpus and keeps a small SQLite database mapping each local file to its document UID. It uploads new files, replaces modified ones, deletes removed ones, and resumes interrupted transfers. Change detection filters on size and mtime, then confirms with a SHA-256 hash. Uploads run concurrently (five workers by default) through the three-step init → transfer → commit sequence. Requires **Python 3.11+** and [uv](https://docs.astral.sh/uv/). ```shell uv sync cp config.example.toml /etc/verbatim/sync.toml # then edit: org id, keys dir, key id, corpus ``` | Command | What it does | | -------------- | ---------------------------------------------------- | | `--init-db` | Create or upgrade the state database | | `--check` | Validate the configuration and test API connectivity | | `--scan-only` | Catalog local files without calling the API | | `--dry-run` | Show what would be uploaded, change nothing | | *(no flag)* | Run the full synchronization | | `--stats` | Print sync status and statistics | | `--rebuild-db` | Rebuild the local database from the corpus metadata | Authentication uses the same RSA key pair as everything else — generate it with `python-token-builder` and register the public key in the backoffice. ### `client-demo` — end-to-end examples Collected examples of REST client implementations against the API — the place to look for a complete "upload a document, wait for it to be ready, ask a question" flow rather than a single call. 🚧 This repository is being populated; the SDK repositories above each ship usage snippets in their README in the meantime. *** ## How the clients are generated The SDKs are produced with [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) from the published specification: > The spec is the **source of truth**. If you need a language we do not ship — Go, C#, Rust, PHP, Ruby — point the generator at that URL and you will get an equivalent client: ```shell brew install openapi-generator openapi-generator generate \ -i https://www.verbatim-ai.com/api-docs/openapi.json \ -g go \ -o ./verbatim-go-client ``` You can also explore the API interactively in the [Swagger playground](https://www.verbatim-ai.com/api-docs/swagger/) — paste a JWT minted with `python-token-builder` and call the endpoints directly. *** ## Which one do I need? | If you want to… | Use | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Call the API from an application | The SDK for your language, above | | Get a token to test with | [`python-token-builder`](https://github.com/verbatim-ai/python-token-builder) | | Push a folder of documents into a corpus | [Documentation here](https://verbatim-ai.gitbook.io/docs/file-dir-sync) - [`file-directory-sync`](https://github.com/verbatim-ai/file-directory-sync) | | Add a chatbot to a website | The [JS Chatbot Widget](https://gitlab.com/verbatim.cloud/backend/genai-server/-/tree/develop/docs/\[widget-installation-guide.md]\(https:/verbatim-ai.gitbook.io/docs/widget-website?fallback=true\)/README.md) — no SDK required | | Use a language we don't publish | Generate a client from the OpenAPI spec | *** ## Issues and contributions Open an issue on the relevant repository. For the generated SDKs, report the problem against the API or the spec rather than the generated code — the fix belongs upstream, and the client is rebuilt from it. --- # 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/clients.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.