{
  "openapi": "3.1.0",
  "info": {
    "title": "Meridian Metrics Export API",
    "version": "1.0.0",
    "description": "Stable schema 1.0 metrics export API. /api/v1/lm/agents and /api/v1/lm/metrics are permanent aliases of the canonical operations.",
    "contact": {
      "email": "hello@onaro.io"
    }
  },
  "servers": [
    {
      "url": "https://api.onaro.io",
      "description": "Production; routes return 404 on other hosts. Permanent aliases: GET /api/v1/lm/agents and GET /api/v1/lm/metrics."
    }
  ],
  "paths": {
    "/api/v1/metrics/agents": {
      "get": {
        "operationId": "metrics_export_list_agents_v1",
        "summary": "Discover active agents",
        "description": "Returns active, recently observed agents visible to the integration key.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful metrics export response.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Current per-key logical-route limit per UTC minute.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in the current UTC-minute window.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDiscoveryResponse"
                },
                "example": {
                  "schema_version": "1.0",
                  "as_of": "2026-09-17T03:00:00Z",
                  "agents": [
                    {
                      "id": "agent_01HZX4",
                      "name": "Invoice Agent",
                      "workspace": "production",
                      "model": "gpt-5",
                      "team": "Finance",
                      "cost_center": "CC-100",
                      "status": "active"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid integration key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the metrics:read scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Per-key logical-route rate limit exceeded.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Current per-key logical-route limit per UTC minute.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in the current UTC-minute window.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "Retry-After": {
                "description": "Seconds until the current rate-limit window resets.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/metrics/current": {
      "get": {
        "operationId": "metrics_export_get_current_v1",
        "summary": "Collect current metrics",
        "description": "Returns tenant and per-agent spend, usage, budget, anomaly, and attribution metrics.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful metrics export response.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Current per-key logical-route limit per UTC minute.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in the current UTC-minute window.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentMetricsResponse"
                },
                "example": {
                  "schema_version": "1.0",
                  "as_of": "2026-09-17T03:00:00Z",
                  "currency": "USD",
                  "portal": {
                    "spend_rate_hour": 42.18,
                    "spend_today": 510.03,
                    "spend_mtd": 9042.77,
                    "active_agents": 18,
                    "attribution_coverage_pct": 97.2
                  },
                  "agents": [
                    {
                      "id": "agent_01HZX4",
                      "spend_current_hour": 3.42,
                      "spend_today": 28.1,
                      "spend_mtd": 642.7,
                      "tokens_in_rate": 12500,
                      "tokens_out_rate": 4100,
                      "task_count_hour": 27,
                      "cost_per_task": 0.126667,
                      "budget_burn_pct": 62.5,
                      "anomaly_score": 0.31
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid integration key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the metrics:read scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Per-key logical-route rate limit exceeded.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Current per-key logical-route limit per UTC minute.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in the current UTC-minute window.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "Retry-After": {
                "description": "Seconds until the current rate-limit window resets.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mrk_live_<32 base62 characters>",
        "description": "Tenant integration key with the metrics:read scope."
      }
    },
    "schemas": {
      "DiscoveredAgent": {
        "type": "object",
        "required": [
          "id",
          "name",
          "workspace",
          "model",
          "team",
          "cost_center",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "workspace": {
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "team": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost_center": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "const": "active"
          }
        }
      },
      "AgentDiscoveryResponse": {
        "type": "object",
        "required": [
          "schema_version",
          "as_of",
          "agents"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiscoveredAgent"
            }
          }
        }
      },
      "AgentMetrics": {
        "type": "object",
        "required": [
          "id",
          "spend_current_hour",
          "spend_today",
          "spend_mtd",
          "tokens_in_rate",
          "tokens_out_rate",
          "task_count_hour",
          "cost_per_task",
          "budget_burn_pct",
          "anomaly_score"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "spend_current_hour": {
            "type": "number"
          },
          "spend_today": {
            "type": "number"
          },
          "spend_mtd": {
            "type": "number"
          },
          "tokens_in_rate": {
            "type": "integer"
          },
          "tokens_out_rate": {
            "type": "integer"
          },
          "task_count_hour": {
            "type": "integer"
          },
          "cost_per_task": {
            "type": "number"
          },
          "budget_burn_pct": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "anomaly_score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "PortalMetrics": {
        "type": "object",
        "required": [
          "spend_rate_hour",
          "spend_today",
          "spend_mtd",
          "active_agents",
          "attribution_coverage_pct"
        ],
        "properties": {
          "spend_rate_hour": {
            "type": "number"
          },
          "spend_today": {
            "type": "number"
          },
          "spend_mtd": {
            "type": "number"
          },
          "active_agents": {
            "type": "integer"
          },
          "attribution_coverage_pct": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CurrentMetricsResponse": {
        "type": "object",
        "required": [
          "schema_version",
          "as_of",
          "currency",
          "portal",
          "agents"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "portal": {
            "$ref": "#/components/schemas/PortalMetrics"
          },
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentMetrics"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string"
          }
        }
      }
    }
  }
}