Record numeric, categorical and boolean scores against a thread, message or run.
A score records one named value against a thread, a message or a run. A browser sends scores with an authenticated token on the project's frontend host, and a server sends them to https://backend.assistant-api.com with an API key and the Aui-User-Id and Aui-Workspace-Id headers; see Conventions for hosts and credentials, and Errors for shared errors. An API key write is scoped to the project. A JWT write is scoped to the user's workspace.
The score object
| Field | Type | Meaning |
|---|---|---|
score_id | string | The identifier of the stored score. |
name | string | The score name. |
data_type | enum | numeric, categorical or boolean. |
value | number or null | The numeric value, or 1 or 0 for a boolean score. |
string_value | string or null | The categorical value. It is null for numeric and boolean scores. |
source | enum | end_user, human, evaluator or api. |
comment | string or null | The optional comment recorded with the score. |
source and comment are returned by GET /v1/projects/scores, not by POST /v1/scores.
Create a score
POST /v1/scores| Field | Type | Required | Rules |
|---|---|---|---|
name | string | yes | 1 to 64 characters and matches /^[A-Za-z0-9_.-]+$/. |
data_type | enum | yes | One of numeric, categorical or boolean. |
value | number or boolean | conditional | Required and must be a number for numeric. For boolean, only true, false, 1 or 0 is accepted. Forbidden for categorical. Boolean values are stored as 1 or 0. |
string_value | string | conditional | Required for categorical, 1 to 255 characters. Forbidden for numeric and boolean. |
comment | string | no | 1 to 2,000 characters when present. |
thread_id | string | conditional | 1 to 48 characters. Required for a thread target or a message target. |
message_id | string | conditional | 1 to 48 characters. Required for a message target. |
run_id | string | conditional | 1 to 48 characters. Required for a run target. |
Exactly one target is required. A message target has both message_id and thread_id and no run_id; a run target has run_id alone; a thread target has thread_id alone. With no target, validation reports a score must target a message, run, or thread. With any other target combination, validation reports a score must target exactly one message, run, or thread.
The type validation messages are value is required for numeric scores, boolean scores require value to be true, false, 1, or 0, string_value is required for categorical scores, categorical scores cannot include value and only categorical scores can include string_value.
curl https://backend.assistant-api.com/v1/scores \
-H "Authorization: Bearer $ASSISTANT_API_KEY" \
-H "Aui-User-Id: user_123" \
-H "Aui-Workspace-Id: workspace_123" \
-H "Content-Type: application/json" \
-d '{
"name": "answer_quality",
"data_type": "numeric",
"value": 1,
"comment": "Resolved the request",
"thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U"
}'{
"name": "answer_quality",
"data_type": "numeric",
"value": 1,
"comment": "Resolved the request",
"thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U"
}{
"score_id": "score_0qzof3jPoDwr7K3agyJN3D4U",
"name": "answer_quality",
"data_type": "numeric",
"value": 1,
"string_value": null
}| Status | Body | When |
|---|---|---|
201 | { score_id, name, data_type, value, string_value } | The score was stored. |
400 | { "error": "Schema validation error", "details": […] } | A field failed validation. The messages include value is required for numeric scores, boolean scores require value to be true, false, 1, or 0, string_value is required for categorical scores, categorical scores cannot include value, only categorical scores can include string_value, a score must target a message, run, or thread and a score must target exactly one message, run, or thread. |
400 | { "error": "message_id must belong to thread_id" } | The message is not in the supplied thread. |
404 | { "error": "Thread not found" } | The target thread is not visible in the caller's scope. |
404 | { "error": "Run not found" } | The target run is not visible in the caller's scope. |
The score source is api for a server API key write, end_user for user feedback or a JWT score write, human for a dashboard manual score including a conversation review, and evaluator for an evaluator rule's verdict. Scores are upserted per target and author. Message scores conflict on (message_id, name, author_id), run scores on (run_id, name, author_id), and thread scores on (thread_id, name, author_id); a conflict updates the existing row and its updated_at. Read scores back from the project API.
On the dashboard thread page, a team member can record a whole-conversation review as Good, Needs work, or Unclear, with an optional note. It is stored as a thread-only score, with no message or run, using name: "review", source: "human", data_type: "categorical", and a string_value of good, needs_work, or unclear. The optional note is stored in comment. There is one review for each reviewer and thread. Score list endpoints return reviews like any other score.
Message feedback
The thumbs in the assistant-ui components call message feedback, which accepts an optional comment and writes one boolean score named feedback per message and user. An end user's thumb is a feedback score and is never a review. Read it back like any other score.