PR #267 - recoupable/docs

Amends the GET /api/catalogs/measurements contract (docs#265, merged) for the data plumbing v2: artist-scoped valuation bucket of recoupable/chat#1850.

What changed (all in `api-reference/openapi/releases.json`; the reference page `api-reference/songs/catalog-measurements.mdx` is frontmatter-only and unchanged)

New optional query param artist_account_id (uuid): when present, measurements + valuation cover only the catalog's songs linked to that artist account via song_artists; when absent, the whole catalog. A song linked to multiple artists counts for each. Malformed values → 400 (400 description updated).
New response field artist_account_id (uuid, nullable): echoes the applied filter — the uuid when the response was artist-scoped, null when whole-catalog. Lets clients (the chat homepage hero) verify the response scope before rendering artist-labeled numbers, instead of showing wrong-scoped money against a pre-v2 deployment that ignores the unknown param.
Explicit no-cap semantics: measurements and total_streams now state they cover ALL matching songs with no row cap. The current implementation silently truncates at 1,000 rows (live repro: https://github.com/recoupable/api/pull/757#issuecomment-4898568413) — being fixed in the api v2 PR.

The OpenAPI JSON diff is purely additive/amending on the measurements path + response schema; every other path/schema is byte-identical (verified by structural diff after a parse round-trip).

Amended 2026-07-07

Per the dated decision on chat#1850: whole-scope SQL aggregates + a caller-paginated measurements array replace the loop-to-exhaustion read. The contract now documents page/limit params (defaults 1/50, max 100), the pagination envelope (same shape as catalog songs), and a top-level measured_song_count; the aggregates (measured_song_count, total_streams, valuation) explicitly cover the ENTIRE scope regardless of pagination. Filter + echo semantics unchanged. Review feedback applied: the endpoint description stays the short docs#265 original; all details live on params/schemas.

Renamed 2026-07-07

The endpoint is now GET /api/catalogs/{catalogId}/measurements — path for identity, query for the optional modifiers (artist_account_id, page, limit), matching the research measurements family (REST decision on recoupable/chat#1850). Review feedback also applied: short endpoint description, details on params/schemas.

Merge order

This docs PR merges first, then recoupable/database#42 (the RPCs), then the api v2 implementation PR (recoupable/api#763), then the chat#1852 hero rework. Contract-first per documentation-driven development.

Refs recoupable/chat#1850.

🤖 Generated with Claude Code

Summary by cubic

Respecs the v2 catalog measurements API: moves catalogId into the path and adds artist-scoped reads with caller pagination while keeping aggregates full-scope with no row cap. Supports chat#1850 with artist-scoped valuation and safer client rendering via scope echoes.

New Features
- Optional artist_account_id query param; response echoes artist_account_id; malformed values return 400.
- Caller-paginated measurements with page/limit (default 1/50, max 100) and a pagination envelope; rows sorted by play count; invalid values return 400.
- New measured_song_count; aggregates (measured_song_count, total_streams, valuation) cover the entire scope regardless of pagination — no row cap.
Refactors
- Endpoint is now GET /api/catalogs/{catalogId}/measurements; catalogId is a required path param (uuid).
- 400 now covers malformed catalogId and invalid page/limit; endpoint description stays short with details in params/schemas.

Summary by CodeRabbit

Documentation
- Clarified the catalog measurements API to support optional artist-level filtering.
- Documented that results are exhaustive with no row cap and that only catalog songs linked to the selected artist are included.
- Added a response field that echoes the applied artist filter, or shows no filter when unscoped.
- Expanded error details for invalid artist identifier input.