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, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication 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.
typeenumOptional
Evaluator execution type. Legacy rows may contain legacy type values.
environmentstringOptional
Environment associated with the score.
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.

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

Human-readable evaluator name, when available.

scorerstring or nullOptional

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

log_idstring or nullOptional

Associated log/span ID.

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

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error