Assert Metrics for a Metric Block

post/extensions/roboledger/{graph_id}/operations/assert-metrics

Writes externally-observed metric values (usage counts, marketing numbers, hand-carried figures) into the period's standing factset_type='metric' FactSet with AssertedProvenance — the observation sibling of compute-metrics. One standing FactSet per (structure, entity, period_end); re-asserting a period replaces its facts. Structures carrying Derive rules are compute-owned and rejected: asserted and derived metric series keep disjoint structures. Observations must resolve to concepts on the structure's presentation catalog. Deterministic and non-AI — no credits consumed.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

structure_idrequired

string

Metric block structure (block_type='metric') to assert into.

period_endrequired

string (date)

Period end the observations are for — instant concepts (a follower count at month end) land as of this date; duration concepts (monthly downloads) end on it.

period_startoptional

string (date)

Window start for duration concepts and the standing FactSet's period_start. Instant concepts ignore it.

entity_idoptional

string

Entity to assert for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).

source_systemrequired

string

Identifier of the asserting system (e.g. 'content-machine') — recorded as the AssertedProvenance source_system.

basis_noteoptional

string

Free-text basis / source reference for the observations.

observationsrequired

MetricObservation[]

Observed values, one per metric concept — duplicates rejected.

MetricObservation fields

Field	Type	Description
`qname`required	string	Metric element qname (e.g. rsx:GithubStars). Must resolve to a concept on the structure's presentation catalog.
`value`required	number	Observed value.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/assert-metrics" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "observations": [
    {
      "qname": "rsx:GithubStars",
      "value": 1240
    },
    {
      "qname": "rsx:NpmDownloads",
      "value": 3811
    }
  ],
  "period_end": "2026-07-31",
  "period_start": "2026-07-01",
  "source_system": "content-machine",
  "structure_id": "str_growth_metrics"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

AssertMetricsResponse

Command-specific result payload

AssertMetricsResponse fields

Field Type Description

structure_idrequired string

entity_idrequired string

period_endrequired string (date)

fact_set_idrequired

string

Standing metric FactSet the observations were written to.

assertedoptional

AssertedMetricLite[]

One metric written by an ``assert-metrics`` run.

AssertedMetricLite fields

Field	Type	Description
`element_id`required	string	Metric element the fact was written for.
`element_qname`required	string	Metric element qname.
`name`required	string	Metric display name.
`value`required	number	Asserted value.
`unit`required	string	Fact unit — 'USD' for monetary, 'days' for days, else 'pure'.
`period_type`required	string	'instant' or 'duration'.
`item_type`optional	string	Format family from the metric element (monetary \| ratio \| percent \| multiple \| days). None means untyped; fall back to unit.

replacedoptional

boolean

True when a prior standing set existed for the period and its facts were replaced.

Default: false

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error