---
title: "Update a metric variant"
method: PUT
path: "/v1/metric/definitions/{idOrSlug}/variants/{variantId}"
tags: ["Metric"]
---

# Update a metric variant

`PUT /v1/metric/definitions/{idOrSlug}/variants/{variantId}`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/metric/definitions/{idOrSlug}/variants/{variantId}`
- Auth: HTTP bearer

Rename a variant, change its configuration, or both. Every configuration change creates a new
immutable version and advances `versionId`; the response carries the advanced value.

**Editing one of Roark’s own variants forks it for your organization.** The response carries the
new variant’s `id`, which will differ from the one in the path, and `isSystem` becomes false. Roark’s
variant is untouched and other organizations keep it. DELETE your fork to go back to it.

Which fields are editable depends on the metric: some Roark metrics lock their prompt or output
configuration, and a locked field is rejected rather than ignored.

## Path parameters

- `idOrSlug` string, required
- `variantId` string, uuid, required

## Request body

- UpdateMetricVariantInput: Change a variant's name, its configuration, or both. Every configuration change creates a new immutable version and advances `versionId`. Editing Roark's own variant forks it for your organization first: the response carries the new variant's id, and other organizations keep the original. Delete that variant to go back to Roark's version.
  - `name` string: Rename the variant. Does not change its configuration, so `versionId` is unaffected. `Default` is reserved.
  - `llmPrompt` string: The rubric this variant applies. LLM judge metrics only.
  - `scaleMin` integer: Scale minimum. SCALE output only.
  - `scaleMax` integer: Scale maximum. SCALE output only.
  - `booleanTrueLabel` string: What a `true` value means. Given to the judge as its polarity rule, so keep it accurate.
  - `booleanFalseLabel` string: What a `false` value means. Given to the judge as its polarity rule, so keep it accurate.
  - `maxClassifications` integer: Maximum classifications returned. CLASSIFICATION output only.
  - `changeReason` string: Free-text audit note recorded on the new version.

## Response `200`

The updated variant, or your organization’s fork of it

- object
  - `data` MetricVariantResponse, required: One named configuration of a metric.
    - `id` string, uuid, required: Unique identifier for the variant.
    - `metricDefinitionId` string, uuid, required: The metric this variant configures.
    - `name` string, required: Name of the variant. "Default" is the one a metric is scored with unless something pins another.
    - `versionId` string, uuid, nullable, required: The variant's current version: an immutable snapshot of its configuration. Editing the variant advances this. Null only for a variant left without one, which cannot be scored until it is configured.
    - `isSystem` boolean, required: True for Roark's own variant, shared by every organization. Editing one forks it for yours; the original is left alone.
    - `isDefault` boolean, required: Whether this is the variant a metric is scored with when nothing pins another.
    - `createdAt` string, required: When the variant was created.
    - `updatedAt` string, required: When the variant was last changed.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-11** `7dab5c606fa0`: 1 info
  - the `llmPrompt` request property's maxLength was increased from `3000` to `20000`
- **2026-10-09** `e7b6b5cc7fa6`: 1 info
  - the `llmPrompt` request property's maxLength was increased from `2000` to `3000`
- **2026-09-04** `7d9ee4f358d1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/metric/definitions/:idOrSlug/variants/:variantId/put.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)