API Referencevalue-metrics

Create a value metric

Adds one value metric — its unit, formula, signal binding and optional monetary conversion — to the value model. The signal must already exist: an event name your organization has sent, or one referenced by usage pricing on an active product. Publishes a new value model version and recalculates delivered value for historical signals.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Request

Body
namestringRequired1-120 characters

Customer-facing metric name.

unitobjectRequired
formulaobjectRequired
signalobjectRequired
The signal that feeds a metric. A metric has exactly one on this surface, matching Value Studio. On update, supplying it replaces the existing binding rather than merging into it.
slugstringOptional>=1 character
Stable identifier. Derived from the name when omitted.
monetaryConversionobjectOptional
categoryenumOptional

Classification: hve = human value equivalent, time = time saved, cost = cost savings, revenue = revenue generated, risk = risk avoided.

descriptionstring or nullOptional

Short customer-facing copy shown on value receipts.

longDescriptionstring or nullOptional
sourceslist of objects or nullOptional

Up to 3 customer-facing citations backing this metric.

expectedActiveVersionintegerOptional
Optimistic concurrency guard. When supplied and it does not match the live active version, the request fails with 409 instead of overwriting a concurrent change.

Response

201
slugstring
namestring
versioninteger
The value model version this write published.

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error
500
Internal Server Error