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

# Create a metric variant

`POST /v1/metric/definitions/{idOrSlug}/variants`

## Request

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

Add a configuration of this metric for your organization, seeded from its Default. Edit it with
PUT to change what it measures, then pin it where you want it used.

Threshold metrics have no variants: their configuration comes from the metric they derive from.
Metrics in a package that manages its own variants reject this too.

## Path parameters

- `idOrSlug` string, required

## Request body

- CreateMetricVariantInput: Create a variant, seeded from the metric's Default configuration. Edit it afterwards with PUT to change what it measures.
  - `name` string, required: Name for the new variant. Must be unique for this metric within your organization and cannot be `Default`.

## Response `201`

The created variant

- 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

> 187 revisions in range; 1 not diffed.

- **2026-09-04** `7d9ee4f358d1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/metric/definitions/:idOrSlug/variants/post.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/1a91a5c90e44?raw)