Delete evaluator

DELETE /api/evaluators/{evaluator_id}

Delete Evaluator

cURL

curl --request DELETE \
  --url https://api.keywordsai.co/api/evaluators/{evaluator_id}/ \
  --header 'Authorization: Bearer <token>'

Permanently deletes an evaluator from your organization.

This action is irreversible. Once an evaluator is deleted, it cannot be recovered. Make sure you want to permanently remove this evaluator before proceeding.

Authentication

All endpoints require API key authentication:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Description
evaluator_id	string	The unique ID of the evaluator to delete

Important Considerations

Impact on Existing Scores

• Existing scores will remain: Scores that have already been created using this evaluator will not be deleted
• Score references: Existing scores will maintain their reference to the deleted evaluator ID
• Historical data: All historical evaluation data remains accessible

Impact on Running Evaluations

• Active evaluations: Any currently running evaluations using this evaluator may fail
• Scheduled evaluations: Future scheduled evaluations using this evaluator will fail
• API integrations: Applications using this evaluator ID will receive 404 errors

Best Practices

1. Check dependencies: Ensure no active integrations are using this evaluator
2. Export configurations: Save evaluator configurations before deletion if you might need them later
3. Update integrations: Update any code or configurations that reference this evaluator
4. Consider archiving: Instead of deleting, consider marking the evaluator as inactive or archived

Examples

Python

import requests

evaluator_id = "0f4325f9-55ef-4c20-8abe-376694419947"
url = f"https://api.keywordsai.co/api/evaluators/{evaluator_id}/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# Confirm deletion before proceeding
confirm = input(f"Are you sure you want to delete evaluator {evaluator_id}? (yes/no): ")
if confirm.lower() == 'yes':
    response = requests.delete(url, headers=headers)
    if response.status_code == 204:
        print("Evaluator deleted successfully")
    else:
        print(f"Error: {response.status_code} - {response.text}")
else:
    print("Deletion cancelled")

Response

Status: 204 No Content

Successful deletion returns an empty response body with status code 204.

(Empty response body)

Pre-deletion Checklist

Before deleting an evaluator, consider the following:

1. Check Active Usage

Python

# Example: Check if evaluator is being used in recent scores
import requests
from datetime import datetime, timedelta

evaluator_id = "your-evaluator-id"
scores_url = "https://api.keywordsai.co/api/scores/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Check for scores created in the last 30 days
thirty_days_ago = (datetime.now() - timedelta(days=30)).isoformat()
params = {
    "evaluator_id": evaluator_id,
    "created_at__gte": thirty_days_ago
}

response = requests.get(scores_url, headers=headers, params=params)
scores = response.json()

if scores.get('count', 0) > 0:
    print(f"Warning: This evaluator has {scores['count']} scores in the last 30 days")
    print("Consider the impact before deletion")
else:
    print("No recent scores found for this evaluator")

2. Export Evaluator Configuration

Python

# Example: Export evaluator configuration before deletion
import requests
import json

evaluator_id = "your-evaluator-id"
url = f"https://api.keywordsai.co/api/evaluators/{evaluator_id}/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Get evaluator details
response = requests.get(url, headers=headers)
evaluator = response.json()

# Save to file
with open(f"evaluator_backup_{evaluator_id}.json", "w") as f:
    json.dump(evaluator, f, indent=2)

print(f"Evaluator configuration saved to evaluator_backup_{evaluator_id}.json")

3. Update Integration Code

Ensure you update any code that references the evaluator:

Python

# Before deletion, update your application code
# Replace hardcoded evaluator IDs with new ones

# OLD CODE:
# evaluator_id = "0f4325f9-55ef-4c20-8abe-376694419947"  # This will be deleted

# NEW CODE:
evaluator_id = "new-evaluator-id-here"  # Use replacement evaluator

Error Responses

404 Not Found

{
  "detail": "Not found."
}

401 Unauthorized

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

403 Forbidden

{
  "detail": "You do not have permission to delete this evaluator."
}

409 Conflict

{
  "detail": "Cannot delete evaluator: it is currently being used in active evaluations. Please wait for evaluations to complete or cancel them before deletion."
}

Recovery Options

If You Accidentally Deleted an Evaluator

Since deletion is permanent, you have these options:

1. Recreate from backup: If you exported the configuration, recreate the evaluator
2. Contact support: For critical evaluators, contact Keywords AI support immediately
3. Check version control: If evaluator configurations are in your codebase

Recreating a Deleted Evaluator

Python

# Example: Recreate evaluator from backup
import requests
import json

# Load backup configuration
with open("evaluator_backup_old-id.json", "r") as f:
    backup_config = json.load(f)

# Prepare creation payload (remove read-only fields)
create_payload = {
    "name": backup_config["name"],
    "type": backup_config["type"],
    "score_value_type": backup_config["score_value_type"],
    "description": backup_config["description"],
    "configurations": backup_config["configurations"],
    "categorical_choices": backup_config.get("categorical_choices"),
    "tags": backup_config.get("tags", [])
}

# Create new evaluator
url = "https://api.keywordsai.co/api/evaluators/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=create_payload)
new_evaluator = response.json()

print(f"New evaluator created with ID: {new_evaluator['id']}")
print("Remember to update your integration code with the new ID")