GET /api/metrics/catalog
Returns the backend-authoritative base metric catalog available to custom metric builders and alert builders.
Request
GET /api/metrics/catalog
Response 200
{
"metrics": [
{
"key": "totalSku",
"name": "Total SKU",
"description": "Total active products in scope",
"scope": "organization",
"format": "number"
},
{
"key": "outboundQuantity",
"name": "Outbound Quantity",
"description": "Total outbound quantity in scope",
"scope": "organization",
"format": "quantity"
}
]
}
GET /api/metrics/definitions
Lists custom metric definitions for the authenticated account's current organization.
Request
GET /api/metrics/definitions
Response 200
{
"metrics": [
{
"id": "uuid",
"orgId": "uuid",
"key": "outflow_ratio",
"name": "Outflow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {
"kind": "div",
"left": {
"kind": "metric",
"key": "outboundQuantity"
},
"right": {
"kind": "metric",
"key": "inboundQuantity"
}
},
"isActive": true,
"createdBy": "uuid",
"createdAt": "2026-04-04T00:00:00.000Z",
"updatedAt": "2026-04-04T00:00:00.000Z"
}
]
}
GET /api/metrics/definitions/:metricId
Returns one metric definition in the current organization scope.
Request
GET /api/metrics/definitions/11111111-1111-1111-1111-111111111111
Response 200
{
"metric": {
"id": "uuid",
"orgId": "uuid",
"key": "outflow_ratio",
"name": "Outflow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {},
"isActive": true,
"createdBy": "uuid",
"createdAt": "2026-04-04T00:00:00.000Z",
"updatedAt": "2026-04-04T00:00:00.000Z"
}
}
POST /api/metrics/definitions
Creates a custom metric definition from validated JSON AST.
Request
POST /api/metrics/definitions
Content-Type: application/json
{
"key": "outflow_ratio",
"name": "Outflow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {
"kind": "div",
"left": {
"kind": "metric",
"key": "outboundQuantity"
},
"right": {
"kind": "metric",
"key": "inboundQuantity"
}
}
}
Response 201
{
"metric": {
"id": "uuid",
"orgId": "uuid",
"key": "outflow_ratio",
"name": "Outflow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {},
"isActive": true,
"createdBy": "uuid",
"createdAt": "2026-04-04T00:00:00.000Z",
"updatedAt": "2026-04-04T00:00:00.000Z"
}
}
PATCH /api/metrics/definitions/:metricId
Updates part or all of an existing metric definition.
Request
PATCH /api/metrics/definitions/11111111-1111-1111-1111-111111111111
Content-Type: application/json
{
"name": "Outbound Flow Ratio",
"isActive": false
}
Response 200
{
"metric": {
"id": "uuid",
"orgId": "uuid",
"key": "outflow_ratio",
"name": "Outbound Flow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {},
"isActive": false,
"createdBy": "uuid",
"createdAt": "2026-04-04T00:00:00.000Z",
"updatedAt": "2026-04-04T01:00:00.000Z"
}
}
DELETE /api/metrics/definitions/:metricId
Deletes a custom metric definition in the current organization scope.
Request
DELETE /api/metrics/definitions/11111111-1111-1111-1111-111111111111
Response 200
{
"metric": {
"id": "uuid",
"orgId": "uuid",
"key": "outflow_ratio",
"name": "Outflow Ratio",
"description": "Share of total flow that is outbound",
"scope": "organization",
"format": "percent",
"definition": {},
"isActive": true,
"createdBy": "uuid",
"createdAt": "2026-04-04T00:00:00.000Z",
"updatedAt": "2026-04-04T00:00:00.000Z"
}
}
POST /api/metrics/definitions/preview
Evaluates a metric definition against live base metric values without persisting it.
Request
POST /api/metrics/definitions/preview
Content-Type: application/json
{
"definition": {
"kind": "div",
"left": {
"kind": "metric",
"key": "outboundQuantity"
},
"right": {
"kind": "metric",
"key": "inboundQuantity"
}
}
}
Response 200
{
"preview": {
"status": "ready",
"value": 0.08
},
"baseMetrics": {
"outboundQuantity": 8,
"inboundQuantity": 100
}
}
GET /api/metrics/inventory/overview
Returns inventory overview card metrics with optional filter and threshold query params.
Request
GET /api/metrics/inventory/overview?stockState=critical&criticalThreshold=5&lowThreshold=15
Response 200
{
"overview": {
"totalSku": 12,
"totalQuantity": 542,
"totalValue": 10934.25,
"criticalCount": 2,
"lowCount": 3
}
}
GET /api/metrics/inventory/movement-trend
Returns grouped daily inbound and outbound movement series.
Request
GET /api/metrics/inventory/movement-trend?days=30&categoryIds=uuid,uuid
Response 200
{
"days": 30,
"trend": [
{
"bucket": "2026-04-01",
"inbound": 55,
"outbound": 13
}
]
}
GET /api/metrics/inventory/movement-summary
Returns aggregate movement totals for the current organization or a filtered product/category scope.
Request
GET /api/metrics/inventory/movement-summary?productId=uuid&days=30
Response 200
{
"scope": {
"productId": "uuid",
"days": 30
},
"summary": {
"movementCount": 9,
"stockInQuantity": 100,
"stockOutQuantity": 50,
"transferInQuantity": 12,
"transferOutQuantity": 6,
"adjustmentIncreaseQuantity": 4,
"adjustmentDecreaseQuantity": 2,
"inboundQuantity": 116,
"outboundQuantity": 58,
"netQuantity": 58
}
}
GET /api/metrics/inventory/category-breakdown
Returns a grouped category value distribution with optional top-N and filter query params.
Request
GET /api/metrics/inventory/category-breakdown?top=3
Response 200
{
"categories": [
{
"categoryId": "uuid",
"categoryName": "Technology",
"skuCount": 2,
"totalQuantity": 900,
"totalValue": 1890000,
"share": 54.01
}
]
}