Eval APIs

Version: aju17f20mq

Use the reference below for request and response fields and operation-specific requirements.

Overview

Read traces and scores, curate datasets, and read evaluation runs. These are evaluation and observability operations.

Authentication

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.

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. To attribute a turn to a dataset run, set the experiment block on send-message or send-message-sync when the turn is sent; there is no operation that associates traces with a run after they have been recorded.

Traces

Read the trace an LLM turn produced, and the observations inside it.

• Get a trace
• List observations
• List traces

Sessions

Group traces by session.

• Get a session
• List sessions

Scores

Read scores and record numeric or boolean reviewer ratings on traces. Other target and value types are not currently supported for score writes.

• Delete a score
• List scores
• Record a score

Score configs

Define the rating scales reviewers pick from.

• Create a score config
• List score configs
• Update a score config

Comments

Free-text notes attached to a trace, observation or session.

• Create a comment
• Delete a comment
• List comments

Datasets

Curate evaluation datasets and the items in them.

• Add a dataset item
• Create a dataset
• List dataset items
• List datasets
• Update a dataset item

Dataset runs

Record what a harness scored on a dataset, and read past runs back.

• Get a dataset run
• List dataset runs

Annotation queues

Queue items for human review and mark them done.

• Complete an annotation queue item
• Create an annotation queue
• Enqueue an item for annotation
• List annotation queue items
• List annotation queues

Overview

Aggregate counts and score averages for a time window.

• Get the eval overview

Server 1

Travila API

https://api.travila.ai

X-API-Key

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.

Authentication credentials

API Key: apiKeyAuth

Setting	Value
Security scheme type	apiKey
header parameter name	X-API-Key

API Key: onBehalfOf

Setting	Value
Security scheme type	apiKey
header parameter name	X-On-Behalf-Of

HTTP: bearerAuth

Setting	Value
Security scheme type	http
Scheme	bearer

Operations

• List traces — POST /api/v1/evals/list-traces
• Get a trace — POST /api/v1/evals/get-trace
• List observations — POST /api/v1/evals/list-observations
• List sessions — POST /api/v1/evals/list-sessions
• Get a session — POST /api/v1/evals/get-session
• List scores — POST /api/v1/evals/list-scores
• Record a score — POST /api/v1/evals/record-score
• Delete a score — POST /api/v1/evals/delete-score
• List score configs — POST /api/v1/evals/list-score-configs
• Create a score config — POST /api/v1/evals/create-score-config
• Update a score config — POST /api/v1/evals/update-score-config
• Create a comment — POST /api/v1/evals/create-comment
• List comments — POST /api/v1/evals/list-comments
• Delete a comment — POST /api/v1/evals/delete-comment
• List datasets — POST /api/v1/evals/list-datasets
• Create a dataset — POST /api/v1/evals/create-dataset
• Add a dataset item — POST /api/v1/evals/add-dataset-item
• List dataset items — POST /api/v1/evals/list-dataset-items
• Update a dataset item — POST /api/v1/evals/update-dataset-item
• List dataset runs — POST /api/v1/evals/list-dataset-runs
• Get a dataset run — POST /api/v1/evals/get-dataset-run
• List annotation queues — POST /api/v1/evals/list-annotation-queues
• Create an annotation queue — POST /api/v1/evals/create-annotation-queue
• Enqueue an item for annotation — POST /api/v1/evals/enqueue-for-annotation
• List annotation queue items — POST /api/v1/evals/list-annotation-queue-items
• Complete an annotation queue item — POST /api/v1/evals/complete-annotation-queue-item
• Get the eval overview — POST /api/v1/evals/get-overview

Document ID: DOC-API-evals-overview. Section identities and revisions.

Section	Stable reference
Overview	DOC-API-evals-overview#overview
Authentication	DOC-API-evals-overview#authentication
Projects	DOC-API-evals-overview#projects
Current API limits	DOC-API-evals-overview#current-adapter-limits
Pagination	DOC-API-evals-overview#pagination
Reading responses	DOC-API-evals-overview#reading-responses
Field naming	DOC-API-evals-overview#field-naming
Traces	DOC-API-evals-overview#reference-group-1
Sessions	DOC-API-evals-overview#reference-group-2
Scores	DOC-API-evals-overview#reference-group-3
Score configs	DOC-API-evals-overview#reference-group-4
Comments	DOC-API-evals-overview#reference-group-5
Datasets	DOC-API-evals-overview#reference-group-6
Dataset runs	DOC-API-evals-overview#reference-group-7
Annotation queues	DOC-API-evals-overview#reference-group-8
Overview	DOC-API-evals-overview#reference-group-9
Server 1	DOC-API-evals-overview#reference-server-1
X-API-Key	DOC-API-evals-overview#authentication-apiKeyAuth