API ReferenceScores

Create a score

Create an evaluation score. Prefer the log-scoped route POST /api/logs/{log_id}/scores/ when creating a score for a known log.

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.

Request

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`.
evaluator_idstringOptional

Evaluator ID. Provide either evaluator_id or evaluator_slug.

evaluator_slugstringOptional

Custom evaluator slug. Provide either evaluator_id or evaluator_slug.

log_idstringOptional

Log/span ID. Required for general score creation when not using the log-scoped route.

timestampdatetimeOptional
Log timestamp. Supplying it can avoid an additional log lookup.
environmentstringOptional
Score environment.
prompt_idstringOptional
prompt_version_numberintegerOptional
dataset_idstringOptional
automation_idstringOptional
scorerstringOptional

Optional score producer for general score creation. Log-scoped routes derive this from the authenticated user.

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.

explanationstringOptional
Optional explanation for the score.

Response

Created 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.
explanationstringOptional
Optional explanation for the score.

Errors

400
Bad Request Error
401
Unauthorized Error