---
title: "Replace evaluator version"
method: PUT
path: "/api/evaluators/{evaluator_id}/versions/{version}/"
tags: ["evaluators"]
---

# Replace evaluator version

`PUT /api/evaluators/{evaluator_id}/versions/{version}/`

Replace a specific evaluator version. Only the current draft (`is_read_only: false`) can be edited.

## Path parameters

- `evaluator_id` string, required
- `version` integer, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string, required
  - `evaluator_slug` string — Organization-scoped evaluator slug.
  - `type` 'llm' | 'human' | 'code'
  - `score_value_type` 'numerical' | 'boolean' | 'percentage' | 'single_select' | 'multi_select' | 'text' | 'json' | 'comment' | 'categorical'
  - `eval_class` 'keywordsai_custom_llm' | 'custom_code' — Optional pre-built evaluator template.
  - `description` string, nullable
  - `score_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaScoreConfig — Score configuration. For numerical/percentage scores, use `min_score` and `max_score`. For select scores, use `choices`.
    - `min_score` number, double
    - `max_score` number, double
    - `choices` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaScoreConfigChoicesItems[]
      - `name` string, required
      - `value` union, required
        - string
        - number, double
        - boolean
  - `passing_conditions` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaPassingConditions — Passing conditions in the standard Respan filter format.
  - `llm_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaLlmConfig — LLM grader configuration. The backend validates this against the selected evaluator form.
    - `model` string
    - `evaluator_definition` string — Prompt/template used by the LLM grader.
    - `scoring_rubric` string
    - `temperature` number, double
    - `max_tokens` integer
    - `top_p` number, double
    - `frequency_penalty` number, double
    - `presence_penalty` number, double
    - `stop` string[]
    - `response_format` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaLlmConfigResponseFormat
    - `tools` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaLlmConfigToolsItems[]
    - `tool_choice` unknown
    - `verbosity` string
  - `code_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaCodeConfig — Code grader configuration.
    - `eval_code_snippet` string — Python code defining `main(eval_inputs)`.
  - `configurations` object — Legacy user-facing configuration object. New clients should prefer `llm_config`, `code_config`, `score_config`, and `passing_conditions`.
  - `categorical_choices` ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaCategoricalChoicesItems[]
    - `name` string, required
    - `value` union, required
      - string
      - number, double
      - boolean
  - `starred` boolean

## Response `200`

Updated evaluator version.

- EvaluatorsReplaceEvaluatorVersionResponse200
  - `id` string, required — Stable evaluator ID shared by all versions.
  - `version_id` string, required — Unique ID for this evaluator version.
  - `version` integer, required — Version number. The first draft is version 0.
  - `is_read_only` boolean, required — Whether this version is committed and immutable.
  - `version_description` string — Commit message for this version.
  - `name` string, required
  - `description` string, nullable
  - `type` 'llm' | 'human' | 'code', required
  - `score_value_type` 'numerical' | 'boolean' | 'percentage' | 'single_select' | 'multi_select' | 'text' | 'json' | 'comment' | 'categorical', required
  - `score_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaScoreConfig — Score configuration. For numerical/percentage scores, use `min_score` and `max_score`. For select scores, use `choices`.
    - `min_score` number, double
    - `max_score` number, double
    - `choices` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaScoreConfigChoicesItems[]
      - `name` string, required
      - `value` union, required
        - string
        - number, double
        - boolean
  - `passing_conditions` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaPassingConditions — Passing conditions in the standard Respan filter format.
  - `llm_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaLlmConfig — LLM grader configuration. The backend validates this against the selected evaluator form.
    - `model` string
    - `evaluator_definition` string — Prompt/template used by the LLM grader.
    - `scoring_rubric` string
    - `temperature` number, double
    - `max_tokens` integer
    - `top_p` number, double
    - `frequency_penalty` number, double
    - `presence_penalty` number, double
    - `stop` string[]
    - `response_format` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaLlmConfigResponseFormat
    - `tools` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaLlmConfigToolsItems[]
    - `tool_choice` unknown
    - `verbosity` string
  - `code_config` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaCodeConfig — Code grader configuration.
    - `eval_code_snippet` string — Python code defining `main(eval_inputs)`.
  - `configurations` object — Legacy user-facing configuration object. New clients should prefer `llm_config`, `code_config`, `score_config`, and `passing_conditions`.
  - `categorical_choices` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaCategoricalChoicesItems[], nullable
    - `name` string, required
    - `value` union, required
      - string
      - number, double
      - boolean
  - `eval_class` 'keywordsai_custom_llm' | 'custom_code' — Optional pre-built evaluator template.
  - `starred` boolean
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `created_by` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaCreatedBy
    - `id` integer
    - `first_name` string
    - `last_name` string
    - `email` string, email
  - `updated_by` ApiEvaluatorsEvaluatorIdVersionsVersionPutResponsesContentApplicationJsonSchemaUpdatedBy
    - `id` integer
    - `first_name` string
    - `last_name` string
    - `email` string, email
  - `is_public` boolean — Whether this is a Respan-managed public evaluator.

## Other responses

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

## Changes

> 6 revisions in range; 2 could not be searched.

- **2026-08-13** `4e064cf81dae` — 36 breaking, 9 warning, 33 info
  - added the new required request property `categorical_choices/items/name`
  - added the new required request property `categorical_choices/items/value`
  - request property `eval_class` was restricted to a list of enum values
  - the request property `code_config` became not nullable
  - …74 more
- **2026-07-31** `c26d550029f8` — 28 breaking, 15 warning, 38 info
  - the request property `description` became not nullable
  - removed the enum value `custom_code` of the request property `eval_class`
  - removed the enum value `keywordsai_custom_llm` of the request property `eval_class`
  - removed `#/components/schemas/ApiEvaluatorsEvaluatorIdVersionsVersionPutRequestBodyContentApplicationJsonSchemaCodeConfig, subschema #2` from the `code_config` request property `oneOf` list
  - …77 more

[Change history](https://skmtc.dev/keywordsai/apis/api-reference/changes/api/evaluators/:evaluator_id/versions/:version/put.md)

---

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