> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Evaluator
> Update an evaluator's description, language, context, or criteria.
**Criteria not included in the request will be permanently deleted.** Always send the full list of criteria you want to keep, not just the changes. See [Evaluator — criteria](/core/evaluator#criteria).
`tag` cannot be changed after creation.
To update an existing criterion, include its `id`. To add a new one, omit `id`. Providing an `id` that does not belong to this evaluator returns `400`.
Non-`strict` criteria weights must still sum to exactly `100` after the update. See [Evaluator — weights](/core/evaluator#weights).
Returns `404` if the evaluator is not found.
## OpenAPI
````yaml api-reference/openapi-evaluators.json POST /update-evaluator
openapi: 3.1.0
info:
title: Heify API — Evaluators
description: Endpoints for creating, retrieving, and managing Evaluators.
version: 1.0.0
servers:
- url: https://api.heify.com
security:
- apiKeyAuth: []
paths:
/update-evaluator:
post:
summary: Update Evaluator
description: >-
Updates an existing evaluator. Scalar fields use PATCH semantics (omit
to leave unchanged). Criteria use merge-by-ID logic — criteria not
included in the request are permanently deleted.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEvaluatorRequest'
examples:
UpdateWithMixedCriteria:
summary: Update fields + update/add criteria
value:
evaluator_id: cd9e6ef7-fd3c-4cf1-9dd5-a5d5dbc8e887
description: descripcion cambiada
language: eu
context: cambiado
criteria:
- id: 141aceae-9fe2-4e55-80c7-707b0aeb9bff
name: Saludo Corporativodf
description: >-
El agente debe presentarse con su nombre completo,
indicar el nombre de la empresa y dar la bienvenida al
cliente.
type: scale
weight: 54
- id: a2b542de-a06a-44ea-9975-20cab95ccaa8
name: Verificación de Identidad
description: >-
El agente debe verificar la identidad del cliente
solicitando al menos dos datos personales.
type: strict
weight: 0
- id: 228dc9a9-30a4-447a-9b0e-7ef01904fc2c
name: Empatía
description: >-
El agente muestra comprensión ante la situación del
cliente.
type: boolean
weight: 42
- name: New Criterion
description: New criterion added during update — no id provided.
type: boolean
weight: 4
responses:
'200':
description: Evaluator updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluatorResponse'
examples:
Success:
summary: Evaluator updated
value:
data:
message: Evaluator updated successfully
evaluator:
evaluator_id: cd9e6ef7-fd3c-4cf1-9dd5-a5d5dbc8e887
tag: nombree
description: descripcion cambiada
language: eu
context: cambiado
criteria:
- id: 141aceae-9fe2-4e55-80c7-707b0aeb9bff
name: Saludo Corporativodf
description: >-
El agente debe presentarse con su nombre completo,
indicar el nombre de la empresa y dar la
bienvenida al cliente.
type: scale
weight: 54
- id: a2b542de-a06a-44ea-9975-20cab95ccaa8
name: Verificación de Identidad
description: >-
El agente debe verificar la identidad del cliente
solicitando al menos dos datos personales.
type: strict
weight: 0
- id: 228dc9a9-30a4-447a-9b0e-7ef01904fc2c
name: Empatía
description: >-
El agente muestra comprensión ante la situación
del cliente.
type: boolean
weight: 42
- id: 932f8c81-044e-405e-8a9c-493003e1f4e5
name: New Criterion
description: >-
New criterion added during update — no id
provided.
type: boolean
weight: 4
created_at: '2026-03-21T15:50:25.898670+00:00'
components:
schemas:
UpdateEvaluatorRequest:
type: object
description: >-
Request body for updating an evaluator. All fields except `evaluator_id`
are optional — omit any field to leave it unchanged.
properties:
evaluator_id:
type: string
format: uuid
description: The evaluator to update.
description:
type: string
nullable: true
maxLength: 250
description: New description. Max 250 characters. Omit to leave unchanged.
language:
type: string
description: >-
New language code for the evaluator. Omit to leave unchanged. See
[Evaluator — language](/core/evaluator#language).
context:
type: string
nullable: true
maxLength: 1000
description: >-
Updated AI context prompt. Max 1000 characters. Omit to leave
unchanged. See [Evaluator — context](/core/evaluator#context).
criteria:
type: array
items:
$ref: '#/components/schemas/UpdateCriterionInput'
description: >-
Full replacement list of criteria using merge-by-ID logic. Criteria
not included will be permanently deleted. Min 1, max 10.
required:
- evaluator_id
CreateEvaluatorResponse:
type: object
properties:
data:
type: object
properties:
message:
type: string
example: Evaluator created successfully
evaluator:
$ref: '#/components/schemas/EvaluatorObject'
UpdateCriterionInput:
type: object
description: >-
A criterion to create or update. Include `id` to update an existing
criterion; omit `id` to create a new one.
properties:
id:
type: string
format: uuid
description: >-
ID of an existing criterion to update. Omit to create a new
criterion. Providing an ID that does not belong to this evaluator
returns `400`.
name:
type: string
minLength: 1
maxLength: 100
description: Name of the criterion. 1–100 characters.
description:
type: string
minLength: 5
maxLength: 2000
description: >-
Detailed description of what the AI should evaluate. 5–2000
characters.
type:
type: string
enum:
- boolean
- scale
- strict
description: >-
Criterion type. See [Evaluator — criterion
types](/core/evaluator#criterion-types).
weight:
type: integer
minimum: 0
maximum: 100
description: >-
Scoring weight (0–100). Must be `0` for `strict` criteria. All
non-`strict` weights must sum to exactly `100`.
required:
- name
- description
- type
- weight
EvaluatorObject:
type: object
description: Full evaluator object as returned by the API.
properties:
evaluator_id:
type: string
format: uuid
description: Unique identifier for this evaluator.
tag:
type: string
description: Name/label for the evaluator (e.g. campaign name).
description:
type: string
nullable: true
description: Description of the evaluator's purpose.
language:
type: string
description: >-
Language used for AI evaluation output. `"df"` = auto-detect from
audio.
context:
type: string
nullable: true
description: Additional context provided to the AI during evaluation.
criteria:
type: array
items:
$ref: '#/components/schemas/CriterionObject'
description: Evaluation criteria for this evaluator.
created_at:
type: string
description: Creation timestamp (ISO 8601).
CriterionObject:
type: object
description: >-
A criterion as returned in API responses. Identical to the input shape
but includes an auto-generated `id`.
properties:
id:
type: string
format: uuid
description: Auto-generated unique identifier for this criterion.
name:
type: string
description: Name of the criterion.
description:
type: string
description: Evaluation instructions provided to the AI.
type:
type: string
enum:
- boolean
- scale
- strict
description: Criterion evaluation type.
weight:
type: integer
description: Weight in the final score. Always `0` for `strict` criteria.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````