Record a score

POST /api/v1/evals/record-score

Records a tenant-side reviewer/operator score.

Resolving the rated turn

Turn addressing is trace-only. A bare conversation ID is qualified with trusted tenant context. Messages without the required historical addressing metadata can be rejected; use an independently verified trace ID in that case.

The API assigns human-source classification and derives rater context from trusted credentials, not the body. A machine key does not identify a human reviewer. A deterministic per-rater/target/name score ID supports replacing a rating, but the current delete operation does not enforce author ownership.

Supported ratings

Use a trace target with numeric or boolean values. The current API maps the resolved target into traceId; categorical/text values and observation/session/dataset-run targets in the schema are not faithfully supported. Use the supported trace/value combinations shown here.

Examples

{
  "targetType": "EVAL_TARGET_TYPE_TRACE",
  "targetId": "<verified-trace-id>",
  "name": "helpfulness",
  "dataType": "SCORE_DATA_TYPE_NUMERIC",
  "numericValue": 4,
  "configId": "<compatible-config-id>"
}

Re-rating and withdrawing

A stable per-rater/target/name score ID does not alone guarantee one current record across dates. The current API omits the original creation timestamp needed for cross-day replacement. Verify read-back after retries or re-rating. Withdrawal must check creator and scope; delete-score currently lacks that creator check and must remain restricted to trusted operators.

Request

Responses

Document ID: DOC-IS-evaluation-api-recordScore. Section identities and revisions.

Section	Stable reference
Overview	`DOC-IS-evaluation-api-recordScore#overview`
Request	`DOC-IS-evaluation-api-recordScore#request`
Responses	`DOC-IS-evaluation-api-recordScore#responses`
Resolving the rated turn	`DOC-IS-evaluation-api-recordScore#resolving-the-rated-turn`
Supported ratings	`DOC-IS-evaluation-api-recordScore#supported-ratings`
Examples	`DOC-IS-evaluation-api-recordScore#examples`
Re-rating and withdrawing	`DOC-IS-evaluation-api-recordScore#re-rating-and-withdrawing`

Record a score

/api/v1/evals/record-score

Resolving the rated turn​

Supported ratings​

Examples​

Re-rating and withdrawing​

Request​

Responses​