Skip to main content
POST
Create revision

Authorizations

Authorization
string
header
required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Headers

Prefer
string

Send return=minimal to get no body back from a write and skip reading the resource: a create answers 201 with only Location, and an update answers 204.

Example:

"return=minimal"

Body

application/json
metricId
string
required

The metric to revise. The new revision becomes the metric's active one, and the previous active one becomes legacy.

Minimum string length: 1
Example:

"metric_123"

parentRevisionId
string

The revision of the metric to revise from. Defaults to the metric's active revision. A revision of another metric answers 404.

Minimum string length: 1
Example:

"revision_123"

name
string

The revision's own name. It shows as "R3: stricter rubric". Omit it to leave the revision with none, so it shows as its label, "R3". A name equal to the metric's name or to the revision's own label stores none. "R" followed by digits is refused unless it is the revision's own label. Unique among the live revisions of the metric, legacy ones included, ignoring case.

Required string length: 1 - 200
Example:

"stricter rubric"

definition
string | null
judgePrompt
string | null
Maximum string length: 20000
evaluatorModelName
string | null

Required for PARTIAL_PROMPT. For CLASSIFIER: The selectable classifier model to run the question under, as listed by GET /evaluatorModels with kind=CLASSIFIER and selectable=true. Omitted or null, the one selectable classifier model is used. When several are selectable, the request is refused with 400 and this field must be sent.

Example:

"gpt-4.1"

evaluationParams
string[] | null
Maximum array length: 20
Required string length: 1 - 64
Example:
areEvalParamsTop
boolean | null
judgeGenerationSettings
object | null

The generation settings this metric's judge runs with. Immutable: changing one creates a revision. Only the settings GET /evaluatorModels reports as configurable for the chosen model take effect; a value the provider rejects ends that evaluation as SKIPPED carrying the provider's own message.

passThreshold
number | null

Score from 0 to 1 at or above which an evaluation of this metric passes. Omitted or null, it defaults to 0.5, or to the parent metric's threshold for a revision.

Required range: 0 <= x <= 1
Example:

0.7

applicabilityScope
enum<string> | null

Which sessions get the applicability check before this metric is judged: PRODUCTION, DEVELOPMENT, ALL or NONE (no check). A session the check finds the metric does not apply to is skipped and no judge call is made. Omitted or null, it defaults to PRODUCTION for a metric the platform scores and NONE for any other. A revision keeps the parent metric's value when the check runs for both. Fixed at create: a change creates a revision. Any value but NONE is refused with a 400 for a metric the platform does not score. A metric that scores only traces is never checked, so it takes NONE and refuses any other value. A metric that also scores another field is checked without traces: on each turn's input and actual output and its other fields. A FULL_PROMPT metric with empty evaluationParams whose judge prompt reads only traces is stored as checked, yet the evaluator judges it without the check. A FULL_PROMPT metric whose evaluationParams list only traces takes NONE even when its judge prompt reads another field: list that field in evaluationParams to get the check. The check runs only where the deployment enables it.

Available options:
NONE,
DEVELOPMENT,
PRODUCTION,
ALL
Example:

"PRODUCTION"

applicabilityThreshold
number | null

The lowest probability, from 0 to 1, that the metric applies to a session at which it is judged. Below it, the session is skipped. Omitted or null, it defaults to 0.5, or to the parent metric's value for a revision when the check runs for both. Fixed at create: a change creates a revision. Refused with a 400 for a metric the platform does not score, and for a metric that scores only traces. The check runs only where the deployment enables it.

Required range: 0 <= x <= 1
Example:

0.7

classifierQuestion
object | null

CLASSIFIER only, and required there: the one question the classifier answers. evaluationParams is derived from its {{ param }} placeholders.

userGroupIds
string[] | null

User groups to link to the revision. Required for a Human Evaluation metric.

Minimum string length: 1
Example:
specificationIds
string[] | null

Specifications to link to the revision.

Minimum string length: 1
Example:

Response

Revision created successfully. On Prefer: return=minimal, or when the read after the write fails, the answer has no body.

id
string
required

Revision ID.

Example:

"revision_123"

metricId
string
required

The metric this revision belongs to.

Example:

"metric_123"

number
integer
required

The revision number within its metric, allocated once when the revision is created and never reused. The revision shows as "R" followed by this number, so 3 is "R3".

Required range: x > 0
Example:

3

parentRevisionId
string | null
required

The revision this one was revised from. Null for the first revision of a metric.

Example:

"revision_122"

name
string | null
required

The name this revision was saved under, when it differs from its metric's name. Null otherwise: read the metric for its name.

Example:

"Accuracy (strict judge)"

isActive
boolean
required
read-only

Whether this is the active revision of its metric: its own legacy date is unset, it is not deleted and it is not being optimized.

legacyAt
string<date-time> | null
required
read-only

Earliest non-null of this revision's own legacy date and its evaluator model's unselectableAt, once that date has passed.

disabledAt
string<date-time> | null
required
read-only

Earliest non-null of the metric's disabled date and this revision's evaluator model's disabledAt.

definition
string | null
required

Name of the built-in evaluator the metric runs, for example json_field_match. Null when the metric names none.

judgePrompt
string | null
required
Example:

"Evaluate the accuracy of the response"

evaluatorModelName
string | null
required
Example:

"gpt-4"

evaluationParams
string[]
required

Ordered list of trace fields the evaluator needs, written in snake_case (e.g. input, actual_output, expected_output, retrieval_context). Determines which data the evaluation engine extracts from each trace. Full list of accepted values: https://docs.galtea.ai/concepts/metric/evaluation-parameters

Example:
areEvalParamsTop
boolean | null
required

When true, evaluationParams are injected at the top level of the evaluator prompt instead of nested inside the conversation context.

judgeGenerationSettings
object | null
required

The generation settings this metric's judge runs with. Null runs the platform defaults. Immutable: changing one creates a revision.

passThreshold
number
required

Score from 0 to 1 at or above which an evaluation of this metric passes. Immutable: changing it creates a revision.

Required range: 0 <= x <= 1
Example:

0.7

applicabilityScope
enum<string>
required

Which sessions get the applicability check before this metric is judged. NONE for a metric the platform does not score. A metric that scores only traces is never checked, so it takes NONE and refuses any other value. A metric that also scores another field is checked without traces: on each turn's input and actual output and its other fields. A FULL_PROMPT metric with empty evaluationParams whose judge prompt reads only traces is stored as checked, yet the evaluator judges it without the check. A FULL_PROMPT metric whose evaluationParams list only traces takes NONE even when its judge prompt reads another field: list that field in evaluationParams to get the check. Immutable: changing it creates a revision. The check runs only where the deployment enables it.

Available options:
NONE,
DEVELOPMENT,
PRODUCTION,
ALL
Example:

"PRODUCTION"

applicabilityThreshold
number | null
required

The lowest probability that the metric applies to a session at which it is judged. Null means the platform default, 0.5. Immutable: changing it creates a revision.

Required range: 0 <= x <= 1
Example:

0.7

classifierQuestion
object
required

The one question of a CLASSIFIER metric; null for every other source.

isBeingOptimized
boolean
required
read-only

Whether the metric is currently being optimized.

optimizationStatus
enum<string> | null
required
read-only

Where an optimization attempt stands. Null for a metric that did not come from an optimization. A candidate waiting for review is legacy until it is activated.

Available options:
OPTIMIZING,
READY_FOR_REVIEW,
FAILED,
NO_IMPROVEMENT,
DECLINED,
ACTIVATED
Example:

"READY_FOR_REVIEW"

optimizationValidation
object | null
required
read-only

How an optimization attempt was validated: the held-out evaluations and, once the optimizer reported, both prompts scored on the search rows and on the held-out rows. Set on an optimization attempt only, and null for any other metric, for an attempt that predates it, and for an attempt copied from another organization.

optimizationRun
object | null
required
read-only

What an optimization attempt ran: the strategies, the step budget and the steps used. Null while the attempt runs, and when it was not reported: an attempt from before the report existed, one run by an older optimizer, a failed run, an attempt copied from another organization, or a metric that is not an optimization attempt. Null never means a run of 0 steps.

specificationIds
string[]
required

Specifications linked to this revision. A MEMBER caller sees only the specifications of the products it can read.

Example:
userGroupIds
string[]
required

User groups of the caller's organization linked to this revision.

Example:
excludedFromAnalyticsAt
string<date-time> | null
required
read-only

When this revision was excluded from analytics. Null when its results still count. The other revisions of the metric are unaffected.

excludedByUserId
string | null
required
read-only

User who excluded this revision from analytics. A repeated exclusion keeps the first user.

createdAt
string<date-time>
required