CDM server silently ignores unknown request body fields; add validation and self-documenting API

[atheurer]

Problem

The CDM query server's POST endpoints use JS destructuring to extract known fields from req.body, which silently ignores any unrecognized fields. This caused a real bug: the agentic-perf review agent sent "breakouts" (plural) instead of "breakout" (singular) to /api/v1/metric-data, and every breakout query silently returned aggregated data with usedBreakouts: [].

The agent tried 10+ breakout dimensions across dozens of API calls — all failed silently because the server never indicated the field name was wrong.

Field naming inconsistency

The CDM API itself is inconsistent:

Endpoint	Field name
POST /api/v1/metric-data	breakout (singular)
POST /api/v1/iterations/supplemental-metric	breakout (singular)
POST /api/v1/iterations/breakout-values	breakouts (plural)

Proposed improvements

1. Unknown-field validation (immediate)

Add a helper function that checks Object.keys(req.body) against the set of known fields for each endpoint. When unknown fields are found, return HTTP 400:

{
  "code": "UNKNOWN_FIELDS",
  "error": "Unknown field(s) in request body: breakouts. Did you mean: breakout?"
}

Apply to at minimum the three breakout-related POST endpoints. The "did you mean?" suggestion helps callers fix typos and plural/singular mismatches quickly.

2. Self-documenting API endpoint (follow-up)

Add GET /api/v1 that returns a JSON schema of all endpoints — method, path, accepted parameters with types, required fields, and descriptions. This lets both humans and LLM agents discover the correct field names programmatically instead of relying on external documentation that can drift from the actual API.

Optionally, GET /api/v1/docs could serve workflow guides (e.g., how to use breakouts, query patterns) that today live in separate skill files maintained outside this repo.

[k-rister]

Should the API have JSON schema for the data that can be used to validate the input(s)?