​
Update Evaluator

PATCH /api/evaluators/{evaluator_id}/ Updates specific fields of an evaluator. Supports partial updates of configuration fields.

​
Authentication

Requires API key authentication. Include your API key in the request headers: 
Authorization: Api-Key YOUR_API_KEY

​
Path Parameters

ParameterTypeDescription
evaluator_idstringThe unique ID of the evaluator to update

​
Request Body

You can update any of the following fields. Only provide the fields you want to update:
FieldTypeDescription
namestringDisplay name for the evaluator
descriptionstringDescription of what the evaluator does
configurationsobjectType-specific configuration settings
categorical_choicesarrayChoices for categorical evaluators
custom_required_fieldsarrayAdditional required fields
starredbooleanWhether the evaluator is starred
tagsarrayTags for organization
Note: Configuration fields are merged with existing values. Non-null values take precedence over existing null values.

​
Examples

​
Update LLM Evaluator Configuration

import requests

evaluator_id = "0f4325f9-55ef-4c20-8abe-376694419947"
url = f"https://api.keywordsai.co/api/evaluators/{evaluator_id}/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "configurations": {
        "evaluator_definition": "Updated: Evaluate response quality with enhanced criteria focusing on accuracy, relevance, completeness, and clarity.",
        "max_score": 10.0,
        "passing_score": 7.0
    }
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

​
Update Basic Information

data = {
    "name": "Enhanced Response Quality Evaluator",
    "description": "Updated evaluator with enhanced quality criteria",
    "starred": True,
    "tags": ["quality", "enhanced", "v2"]
}

response = requests.patch(url, headers=headers, json=data)

​
Update Categorical Choices

data = {
    "categorical_choices": [
        { "name": "Outstanding", "value": 5 },
        { "name": "Excellent", "value": 4 },
        { "name": "Good", "value": 3 },
        { "name": "Fair", "value": 2 },
        { "name": "Poor", "value": 1 }
    ]
}

response = requests.patch(url, headers=headers, json=data)

​
Update Code Evaluator

data = {
    "configurations": {
        "eval_code_snippet": "def evaluate(llm_input, llm_output, **kwargs):\n    # Enhanced length evaluation\n    length = len(llm_output.split())\n    if length < 5:\n        return 1\n    elif length < 20:\n        return 2\n    elif length < 100:\n        return 4\n    else:\n        return 5"
    }
}

response = requests.patch(url, headers=headers, json=data)

​
Response

Status: 200 OK 
{
  "id": "0f4325f9-55ef-4c20-8abe-376694419947",
  "name": "Enhanced Response Quality Evaluator",
  "evaluator_slug": "response_quality_v1",
  "type": "llm",
  "score_value_type": "numerical",
  "eval_class": "",
  "description": "Updated evaluator with enhanced quality criteria",
  "configurations": {
    "evaluator_definition": "Updated: Evaluate response quality with enhanced criteria focusing on accuracy, relevance, completeness, and clarity.",
    "scoring_rubric": "1=Poor, 2=Fair, 3=Good, 4=Very Good, 5=Excellent",
    "llm_engine": "gpt-4o-mini",
    "model_options": {
      "temperature": 0.1,
      "max_tokens": 200
    },
    "min_score": 1.0,
    "max_score": 10.0,
    "passing_score": 7.0
  },
  "created_by": {
    "first_name": "Keywords AI",
    "last_name": "Team",
    "email": "admin@keywordsai.co"
  },
  "updated_by": {
    "first_name": "Keywords AI",
    "last_name": "Team",
    "email": "admin@keywordsai.co"
  },
  "created_at": "2025-09-11T09:43:55.858321Z",
  "updated_at": "2025-09-11T09:43:55.930792Z",
  "custom_required_fields": [],
  "categorical_choices": [],
  "starred": true,
  "tags": ["quality", "enhanced", "v2"]
}

​
Configuration Update Behavior

  • Merge Strategy: Configuration fields are merged with existing values
  • Precedence: Non-null values in the update request take precedence
  • Partial Updates: You can update individual configuration fields without affecting others
  • Validation: Updated configurations are validated according to the evaluator type

​
Error Responses

​
400 Bad Request

{
  "configurations": [
    "Configuration validation failed: 1 validation error for KeywordsAICustomLLMEvaluatorType\nscoring_rubric\n  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]"
  ]
}

​
401 Unauthorized

{
  "detail": "Your API key is invalid or expired, please check your API key at https://platform.keywordsai.co/platform/api/api-keys"
}

​
404 Not Found

{
  "detail": "Not found."
}