Scores

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, credentials and shared errors.

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.

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

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"
  }'

Request

{
  "name": "answer_quality",
  "data_type": "numeric",
  "value": 1,
  "comment": "Resolved the request",
  "thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U"
}

Response

{
  "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`	`{ "success": false, "error": … }`	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 an API key and end_user for a JWT. 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.

Message feedback

The thumbs in the assistant-ui components call message feedback, which writes one boolean score named feedback per message and user. Read it back like any other score.