A REST API for defining audit rubrics, submitting conversation batches, and retrieving defensible quality scores at population scale.
Audibot evaluates customer-service conversations against a rubric the customer already uses with its human auditors. It replaces a 2 % sampling workflow with 100 % coverage, returning per-conversation scores with transcript-span evidence attached to every rating.
The v2 API is a breaking revision of the v1 surface shipped in 2025-09. It introduces rubric versioning, streamed result delivery, and a normalized evidence schema. This document is the authoritative contract for integrators.
In scope: the REST surface for submitting audits, retrieving results, and managing rubrics. Also in scope: the data contract, error taxonomy, idempotency rules, and migration from v1 endpoints.
Out of scope: the LLM backbone configuration, scoring-model weights, batching optimization, and the internal worker architecture. These are implementation details and may change without a spec revision1.
v2 is not backward-compatible with v1 at the wire level. Endpoints are served at /v2/*. The v1 surface at /v1/* continues to receive security fixes through 2026-09 and is then decommissioned.
Rubric IDs are not portable between v1 and v2. A rubric defined via POST /v1/rubrics must be re-authored against the v2 schema; see §4 for the migration path.
We chose a hard-break versioning strategy (separate path prefix, no graceful fallback) because v1's single-score rubric shape cannot represent v2's criterion-level evidence attachments. A translating shim layer would misreport uncertainty and was judged worse than a migration window.
v2 also removes the synchronous /audits/evaluate endpoint. All audits are now asynchronous batches — a design change motivated by the latency variance observed when v1 was deployed against > 5k-conversation populations.
| Method | Path | Purpose | Idempotent |
|---|---|---|---|
POST | /v2/audits | Submit a batch for scoring | yes* |
GET | /v2/audits/{id} | Fetch batch status and summary | yes |
GET | /v2/audits/{id}/results | Stream per-conversation results (NDJSON) | yes |
POST | /v2/rubrics | Register a rubric version | yes* |
GET | /v2/rubrics/{id} | Fetch a rubric definition | yes |
POST | /v2/rubrics/{id}/versions | Bump a rubric's version | no |
* Idempotent with an Idempotency-Key request header; see §2.3.
Submit a batch of conversations against a rubric. Returns a batch handle; scoring proceeds asynchronously.
latest. Pinned versions are recommended for reproducibility.{id, transcript}. Transcripts are a linear list of {role, text, timestamp} turns.batch.completed POST when scoring finishes.POST /v2/audits HTTP/1.1
Host: api.ontopix.ai
Content-Type: application/json
Idempotency-Key: 01JC8YW2R3PQ1N1NQ6CV1Z0KFP
{
"rubric_id": "7c5b1d4e-…",
"rubric_version": "3.2.0",
"conversations": [
{ "id": "c_001", "transcript": […] },
{ "id": "c_002", "transcript": […] }
],
"callback_url": "https://customer.example/audibot/hook"
}{
"batch_id": "b_01JC8YWR9K…",
"status": "queued",
"conversation_count": 2,
"rubric_version": "3.2.0",
"created_at": "2026-04-23T09:12:04Z"
}Pin rubric_version in production. Leaving it at latest silently changes scoring behavior the next time the rubric is republished, which defeats trend analysis across consecutive batches.
A rubric is a versioned, immutable list of criteria. Each criterion has a weight, a prompt the evaluator LLM uses to score, and a scale. Weights within a rubric must sum to 1.0 ± 0.001.
| Field | Type | Notes |
|---|---|---|
id | uuid | Assigned by server on first POST. |
version | semver | Immutable per (id, version) pair. |
criteria[] | Criterion[] | Ordered; display order preserved. |
min_score, max_score | float | Scale bounds for the aggregate score. |
created_at | datetime | RFC 3339 UTC. |
interface Criterion {
// Stable across versions of the rubric.
id: string;
name: string;
weight: number; // 0..1; rubric weights sum to 1
prompt: string; // LLM instruction
scale: {
type: "ordinal" | "continuous";
labels?: string[]; // required for ordinal
range?: [number, number]; // required for continuous
};
}Each AuditResult carries evidence per criterion: one or more transcript spans the evaluator relied on, plus a short reasoning string. Disputes are resolved by pointing at the evidence, not by re-running the scorer.
interface AuditResult {
conversation_id: string;
rubric_version: string;
overall_score: number;
criterion_scores: {
criterion_id: string;
score: number;
evidence: Evidence[];
}[];
}
interface Evidence {
turn_index_start: number;
turn_index_end: number;
excerpt: string; // verbatim text
reasoning: string; // ≤ 240 chars
}Evidence excerpts are verbatim substrings of the turn text at turn_index_start..turn_index_end. Consumers can diff them against their own transcript store to verify that no span has drifted between submission and result delivery.
v1 and v2 coexist at /v1/* and /v2/* respectively through 2026-09. After that date v1 returns 410 Gone with a Sunset header pointing at this spec2.
| Area | v1 | v2 |
|---|---|---|
| Rubric shape | Flat scoresheet (single score per conversation) | Weighted criteria, per-criterion scores and evidence |
| Scoring mode | Sync (POST /evaluate) + async batches | Async batches only |
| Evidence | Free-text blob | Structured transcript spans + verbatim excerpt |
| Rubric versioning | Implicit; latest applies | Explicit semver; pinning recommended |
| Result delivery | Single JSON envelope | NDJSON stream from /audits/{id}/results |
Recommended order of operations for integrators migrating in place:
rubric_version in all production calls.Preserving criterion IDs across the migration is explicit rather than automatic because we cannot verify that the meaning of a criterion is preserved across a rubric rewrite — only the caller can. Making it the caller's choice keeps the audit trail clean: a v2 criterion with the same ID as a v1 criterion is an explicit claim of semantic continuity.
The full comparison matrix and per-endpoint diff are published alongside this spec at packages/channels/document/examples/ in the stylebook repository.
ADR-017 · Audibot model pinning. Not part of the v2 contract.Sunset header semantics.