Metrics

Metrics are standing workspace or Area signals. The router exposes list, create, update, delete and reading creation; there is no individual Metric GET or readings-list REST route. List includes the latest 30 readings per Metric. Definition writes require company write permission.

Examples use the environment variables from Overview. UUID placeholders must be replaced with your own IDs.

GET /api/metrics

Auth: Workspace member with access to this resource.

Request: Query area_id?:UUID, scope?:"company" (cannot combine with area_id).

Response: {metrics:MetricResponse[]}.

Status: 200. Authentication and resource-access errors follow Overview.

curl -sS -X GET "$MELSO_URL/api/metrics" \
  -H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"

POST /api/metrics

Auth: Workspace member with access to this resource.

Request: metric:string, direction:"maximize"|"minimize"|"maintain", measurement_source:string, cadence:"daily"|"weekly"|"monthly"|"quarterly", unit:string, optional area_id:UUID|null, target_value:number|null, guardrail_min:number|null, guardrail_max:number|null, idempotency_key:string.

Response: MetricResponse.

Status: 201; 400 validation; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow Overview.

curl -sS -X POST "$MELSO_URL/api/metrics" \
  -H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" -d '{"metric":"Qualified leads","direction":"maximize","measurement_source":"CRM","cadence":"weekly","unit":"leads"}'

PATCH /api/metrics/{id}

Auth: Workspace member with access to this resource.

Request: Any subset of the creation fields.

Response: MetricResponse.

Status: 200; 400 validation; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow Overview.

curl -sS -X PATCH "$MELSO_URL/api/metrics/$ID" \
  -H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" -d '{"target_value":50}'

DELETE /api/metrics/{id}

Auth: Workspace member with access to this resource.

Request: Path: Metric UUID; optional definition idempotency key.

Response: {company_commit_sha:string}.

Status: 200; 403 definition-write denied; 409 activation conflict. Authentication and resource-access errors follow Overview.

curl -sS -X DELETE "$MELSO_URL/api/metrics/$ID" \
  -H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" -d '{}'

POST /api/metrics/{id}/readings

Auth: Workspace member with access to this resource.

Request: value:number required, note?:string. Measurement time is assigned by the server.

Response: Updated MetricResponse.

Status: 200; 400 missing value. Authentication and resource-access errors follow Overview.

curl -sS -X POST "$MELSO_URL/api/metrics/$ID/readings" \
  -H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" -d '{"value":42,"note":"Weekly CRM count"}'

MetricResponse

Source: server/internal/handler/metric.go (MetricResponse). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.

MetricReadingResponse

Source: server/internal/handler/metric.go (MetricReadingResponse). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.