Eval APIs
Read traces and scores, curate datasets, and register evaluation runs. These are evaluation and observability operations.
Use an authorized backend sk_… key in X-API-Key; most evaluation operations do not need an end-user identity; record-score requires an attributable verified subject. A console JWT belongs to the separate console surface. See Authentication.
Projects
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
User IDs in read filters identify evaluated subjects; they do not assert the caller’s identity. Machine credentials do not establish a human reviewer. Reviewer attribution is taken from trusted caller context when available. HTTP 424 means evaluation is not provisioned for the selected scope. Contact your Travila operator; repeating the same request will not provision it.
Current API limits
record-score currently maps numeric and boolean values and sends the resolved target as a trace ID. Categorical/text and observation/session/dataset-run scoring are not faithfully implemented despite their schema enum values. delete-score does not currently enforce per-author ownership. Restrict this API to trusted evaluation operators until those controls are qualified. Run registration does not execute a dataset or validate gold-answer eligibility.
Pagination
Cursor lists are list-traces, list-observations, list-scores, list-sessions and list-dataset-runs. Send pageSize, then the exact returned cursorPage.nextCursor as cursor. Continue after a short or empty page when that cursor is present. Other lists use one-based page/pageSize. Only trace lists can return an optional exact total; an unavailable total is not zero. Keep the same scope, filters and time window across pages. Old traces can lack entity tags.
Reading responses
contentRedacted: true reports redaction, while its absence is not proof that content is verbatim or free of sensitive information.
Related guide: Measure and improve quality
Field naming
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
These examples use cursor pagination where indicated. Older API versions can use page numbers. Match your client to the API available to your account. See record-dataset-run for limitations on associating traces after they have been recorded.
Authentication
- API Key: apiKeyAuth
Authorized tenant backend secret key (sk_…). Most evaluation operations do not need an end-user identity; record-score requires an attributable verified subject. Keep the key out of client apps; authorization and provisioning still apply.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
📄️ Overview
Read traces and scores, curate datasets, and register evaluation runs. These are evaluation and observability operations.
📄️ Dataset identity and run provenance
overview}
📄️ Feedback and score attribution
overview}
🗃️ Endpoints
28 items
🗃️ Models
26 items
Document ID: DOC-IS-evaluation-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-IS-evaluation-api-overview#overview |
| Field naming | DOC-IS-evaluation-api-overview#field-naming |
| Authentication | DOC-IS-evaluation-api-overview#authentication |
| Projects | DOC-IS-evaluation-api-overview#projects |
| Current API limits | DOC-IS-evaluation-api-overview#current-adapter-limits |
| Pagination | DOC-IS-evaluation-api-overview#pagination |
| Reading responses | DOC-IS-evaluation-api-overview#reading-responses |