API ReferenceScores

Update a score

Partially update a score by score ID.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

OR
AuthorizationBearer

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

Path parameters

idstringRequired

Score ID returned as id in score responses.

Request

Update one or more score values. Use the value field matching the evaluator `score_value_type`: `numerical`/`percentage` -> `numerical_value`, `boolean` -> `boolean_value`, `single_select`/`multi_select`/`categorical` -> `categorical_value`, `text`/`comment` -> `string_value`, `json` -> `json_value`.
numerical_valuedouble or nullOptional

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring or nullOptional

Text score value. Use for text and legacy comment evaluators.

boolean_valueboolean or nullOptional

Boolean score value. Use for boolean evaluators.

categorical_valuelist of strings or nullOptional

Categorical score values. Use for single_select, multi_select, and legacy categorical evaluators.

json_valuestring or nullOptional

JSON score value encoded as a string. Use for json evaluators.

Response

Updated score.
idstring
Score ID.
created_atdatetime
When the score was created.
typeenum
Evaluator execution type. Legacy rows may contain legacy type values.
environmentstring
Environment associated with the score.
numerical_valuedouble or null

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring or null

Text score value. Use for text and legacy comment evaluators.

boolean_valueboolean or null

Boolean score value. Use for boolean evaluators.

categorical_valuelist of strings or null

Categorical score values. Use for single_select, multi_select, and legacy categorical evaluators.

json_valuestring or null

JSON score value encoded as a string. Use for json evaluators.

is_passedboolean or null
Whether the score passes the evaluator conditions.
costdouble or null
Evaluation cost in USD, when available.
evaluator_idstring or null
Evaluator ID associated with the score.
evaluator_slugstring or null
Evaluator slug associated with the score.
evaluator_namestring or null

Human-readable evaluator name, when available.

scorerstring or null

Who or what produced the score. For log-scoped score writes, the backend derives this from the authenticated user.

log_idstring or null

Associated log/span ID.

prompt_idstring or null
Associated prompt ID, when available.
prompt_version_numberinteger or null
Associated prompt version number, when available.
dataset_idstring or null
Associated dataset ID, when available.
automation_idstring or null
Associated automation ID, when available.
statusstring or null
Evaluation status, when available.
error_messagestring or null
Evaluation error message, when available.
inputsobject
Unified evaluator inputs stored with the score, when available.
evaluatorobject or null
Evaluator metadata when the score is associated with a platform evaluator.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error