Skip to main content
Everything you do inside a project in the Truvec interface is available through a REST API: documents, golden datasets, evaluations, comparisons and the playground. Billing and team management stay in the interface. Use it to automate evaluations, for example re-running a comparison every time your documents change, or to pull results into your own dashboards.

Base URL

Every endpoint path starts with /api, for example https://app.truvec.dev/api/v1/projects. API calls use the same plan and allowances as the interface.

Authentication

Requests are authenticated with a bearer token.
1

Use your Truvec account

Sign in with the email and password of your Truvec account. A teammate’s account works too: API calls act on the projects of the account’s workspace.
2

Get a token

The login endpoint takes a form with your email as username:
3

Send it with every request

Tokens expire after 2 hours. Request a new one when you get a 401 response.

End-to-end example

This script runs the whole workflow: create a project, upload a document, generate and commit a golden dataset, compare two models and print the ranking.
evaluate.sh
Committing a generated dataset without reviewing it is fine for a quick test, but not for decisions. See Build a golden dataset.

Hybrid search and rerankers

To test hybrid search or a reranker, add a pipeline object to an evaluation or to a configuration of a comparison. Without it, the run uses vector search only. See Hybrid search and reranking for what each option does. GET /api/v1/evaluations/pipeline-options lists the rerankers you can use, with their prices. A strategy comparison lists its configurations in variants. The first configuration is the baseline, and every other completed result in results.comparison has a vs_baseline object with the metric differences (hit_rate_delta, recall_delta, mrr_delta, ndcg_delta) and the number of questions fixed and broken:
Models listed in model_ids run with dense search and come before the variants. A comparison needs at least two distinct configurations.

Key resources

Errors

Errors return a JSON body with a detail field: