ROroarkhq
Metric

Update a metric definition

Changed on

Update the editable subset of a custom metric definition, addressed by its UUID or its stable slug. Only the supplied fields are changed; omitted fields are left unchanged. Every update creates a new immutable version; the response carries the advanced versionId. Immutable fields (scope, outputType, calcType, …) are rejected, and which fields are editable depends on the metric (e.g. derived metrics only allow name). Roark's own metrics are rejected here: this endpoint edits the shared definition, which every workspace sees. To change one for your workspace alone, edit its variant with PUT /v1/metric/definitions/{idOrSlug}/variants/{variantId}, which forks it for you and leaves every other workspace on the original.

put/v1/metric/definitions/{idOrSlug}

Request

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

Path parameters

idOrSlugstring required

The metric definition's Roark ID (UUID) or its stable slug (e.g. customer_satisfaction).

Request body

namestring

New name (only for metrics whose name is editable)

llmPromptstring

New LLM prompt (only for LLM_JUDGE metrics whose prompt is editable)

scaleMininteger

New scale minimum (SCALE output only)

scaleMaxinteger

New scale maximum (SCALE output only)

booleanTrueLabelstring

New label for the true case (BOOLEAN output only)

booleanFalseLabelstring

New label for the false case (BOOLEAN output only)

maxClassificationsinteger

New maximum number of classifications (CLASSIFICATION output only)

toolDefinitionIdsstring[]

Replacement set of scoped tool-definition ids (only for metrics whose tool scoping is editable)

supportedContextsstring[]

Replacement set of supported contexts. Omit to leave unchanged. Scope and participantRole cannot change after create, so moving to SEGMENT or TURN grading only works on a PER_PARTICIPANT metric (see create).

formulastring

New formula expression (FORMULA only). Pass sources alongside if the referenced metrics change.

changeReasonstring

Optional free-text audit note recorded on the new version.

slugunknown
metricIdunknown
sourceunknown
organizationIdunknown
projectIdunknown
outputTypeunknown
scopeunknown
participantRoleunknown
calcTypeunknown
supportsMultipleVariantsunknown
analysisPackageIdunknown

Example request

{
  "httpRequest": {
    "url": "https://api.example.com/roark/checks/pin-changed",
    "headers": {
      "Authorization": "Bearer sk_live_..."
    }
  }
}

Response

The updated metric definition (with versionId advanced to the new version)

Changes

  • 0fb1c3b1940aRevision changes
    • breaking

      added to the response property oneOf list for the response status

    • info

      added the new optional request property

    • info

      added HTTP_REQUEST discriminator mapping keys to the response property for the response status

  • 7dab5c606fa0Revision changes
    • info

      the request property's maxLength was increased from 3000 to 20000