---
title: "Replace a score"
method: PUT
path: "/api/scores/{id}/"
tags: ["scores"]
---

# Replace a score

`PUT /api/scores/{id}/`

Replace a score by score ID.

## Path parameters

- `id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `evaluator_id` string — Evaluator ID. Provide either `evaluator_id` or `evaluator_slug`.
  - `evaluator_slug` string — Custom evaluator slug. Provide either `evaluator_id` or `evaluator_slug`.
  - `log_id` string — Log/span ID. Required for general score creation when not using the log-scoped route.
  - `timestamp` string, date-time — Log timestamp. Supplying it can avoid an additional log lookup.
  - `environment` string — Score environment.
  - `prompt_id` string
  - `prompt_version_number` integer
  - `dataset_id` string
  - `automation_id` string
  - `scorer` string — Optional score producer for general score creation. Log-scoped routes derive this from the authenticated user.
  - `numerical_value` number, double, nullable — Numeric score value. Use for `numerical` and `percentage` evaluators.
  - `string_value` string, nullable — Text score value. Use for `text` and legacy `comment` evaluators.
  - `boolean_value` boolean, nullable — Boolean score value. Use for `boolean` evaluators.
  - `categorical_value` string[], nullable — Categorical score values. Use for `single_select`, `multi_select`, and legacy `categorical` evaluators.
  - `json_value` string, nullable — JSON score value encoded as a string. Use for `json` evaluators.
  - `explanation` string — Optional explanation for the score.

## Response `200`

Updated score.

- ScoresReplaceScoreResponse200
  - `id` string, required — Score ID.
  - `created_at` string, date-time, required — When the score was created.
  - `type` 'llm' | 'human' | 'code' | 'function' | 'human_numerical' | 'human_boolean' | 'human_categorical' | 'human_text' | 'custom' — Evaluator execution type. Legacy rows may contain legacy type values.
  - `environment` string — Environment associated with the score.
  - `numerical_value` number, double, nullable — Numeric score value. Use for `numerical` and `percentage` evaluators.
  - `string_value` string, nullable — Text score value. Use for `text` and legacy `comment` evaluators.
  - `boolean_value` boolean, nullable — Boolean score value. Use for `boolean` evaluators.
  - `categorical_value` string[], nullable — Categorical score values. Use for `single_select`, `multi_select`, and legacy `categorical` evaluators.
  - `json_value` string, nullable — JSON score value encoded as a string. Use for `json` evaluators.
  - `is_passed` boolean, nullable — Whether the score passes the evaluator conditions.
  - `cost` number, double, nullable — Evaluation cost in USD, when available.
  - `evaluator_id` string, nullable — Evaluator ID associated with the score.
  - `evaluator_slug` string, nullable — Evaluator slug associated with the score.
  - `evaluator_name` string, nullable — Human-readable evaluator name, when available.
  - `scorer` string, nullable — Who or what produced the score. For log-scoped score writes, the backend derives this from the authenticated user.
  - `log_id` string, nullable — Associated log/span ID.
  - `prompt_id` string, nullable — Associated prompt ID, when available.
  - `prompt_version_number` integer, nullable — Associated prompt version number, when available.
  - `dataset_id` string, nullable — Associated dataset ID, when available.
  - `automation_id` string, nullable — Associated automation ID, when available.
  - `status` string, nullable — Evaluation status, when available.
  - `error_message` string, nullable — Evaluation error message, when available.
  - `inputs` ApiScoresIdPutResponsesContentApplicationJsonSchemaInputs — Unified evaluator inputs stored with the score, when available.
    - `input` unknown
    - `output` unknown
    - `metrics` ApiScoresIdPutResponsesContentApplicationJsonSchemaInputsMetrics
    - `metadata` ApiScoresIdPutResponsesContentApplicationJsonSchemaInputsMetadata
  - `evaluator` ApiScoresIdPutResponsesContentApplicationJsonSchemaEvaluator — Evaluator metadata when the score is associated with a platform evaluator.
  - `explanation` string — Optional explanation for the score.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - Missing or invalid authentication
- `404` — Not Found

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)