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

# Create evaluator version

`POST /api/evaluators/{evaluator_id}/versions/`

Commit the current draft and create the next draft version. Supplying only `version_description` commits the existing draft snapshot; supplying configuration fields commits with changes.

## Path parameters

- `evaluator_id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string
  - `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` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaScoreConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaScoreConfigChoicesItems[]
      - `name` string, required
      - `value` union, required
        - string
        - number, double
        - boolean
  - `passing_conditions` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaPassingConditions — Passing conditions in the standard Respan filter format.
  - `llm_config` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaLlmConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaLlmConfigResponseFormat
    - `tools` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaLlmConfigToolsItems[]
    - `tool_choice` unknown
    - `verbosity` string
  - `code_config` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaCodeConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostRequestBodyContentApplicationJsonSchemaCategoricalChoicesItems[]
    - `name` string, required
    - `value` union, required
      - string
      - number, double
      - boolean
  - `starred` boolean
  - `version_description` string — Commit message for this version.

## Response `201`

Created evaluator version.

- EvaluatorsCreateEvaluatorVersionResponse201
  - `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` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaScoreConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaScoreConfigChoicesItems[]
      - `name` string, required
      - `value` union, required
        - string
        - number, double
        - boolean
  - `passing_conditions` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaPassingConditions — Passing conditions in the standard Respan filter format.
  - `llm_config` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaLlmConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaLlmConfigResponseFormat
    - `tools` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaLlmConfigToolsItems[]
    - `tool_choice` unknown
    - `verbosity` string
  - `code_config` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaCodeConfig — 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` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaCategoricalChoicesItems[], 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` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaCreatedBy
    - `id` integer
    - `first_name` string
    - `last_name` string
    - `email` string, email
  - `updated_by` ApiEvaluatorsEvaluatorIdVersionsPostResponsesContentApplicationJsonSchemaUpdatedBy
    - `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
- `404` — Not Found

## Changes

- **2026-08-13** `4e064cf81dae` — 32 breaking, 17 warning, 47 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
  - request property `score_value_type` was restricted to a list of enum values
  - …92 more
- **2026-07-31** `c26d550029f8` — 36 breaking, 23 warning, 38 info
  - the request property `description` became not nullable
  - removed the enum value `boolean` of the request property `score_value_type`
  - removed the enum value `categorical` of the request property `score_value_type`
  - removed the enum value `comment` of the request property `score_value_type`
  - …93 more

[Change history](https://skmtc.dev/keywordsai/apis/api-reference/changes/api/evaluators/:evaluator_id/versions/post.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)