docs(catalogs): GET /api/catalogs/{catalogId}/valuations — persisted valuation history (chat#1889 row 15)

Merged
SW
4mo ago
+140-1

Contract-first PR for chat#1889 row 15 — the keystone (2026-07-29 reorder decision).

  • New GET /api/catalogs/{catalogId}/valuations: persisted history latest-first, limit (default 30, max 100; limit=1 = current value), rows { low, mid, high, measured_song_count, total_streams, measured_at }; 400/401/404 via the shared Error schema, mirroring the measurements sibling.
  • POST /api/valuation description notes that runs persist a history row.
  • New reference page + nav entry (surfaces in llms.txt).

Merge order: this → database#TBD (catalog_valuations table) → api#TBD (persist + GET). JSON re-validated after anchored edits.

🤖 Generated with Claude Code


Summary by cubic

Adds docs for GET /api/catalogs/{catalogId}/valuations, exposing a persisted valuation history so teams can compute week‑over‑week deltas and fetch the current value with limit=1. Supports the chat#1889 row 15 requirement to persist the valuation band wherever it’s computed.

  • New Features
    • New GET /api/catalogs/{catalogId}/valuations: latest‑first history, limit (default 30, max 100; limit=1 = current), rows include { low, mid, high, measured_song_count, total_streams, measured_at }; 400/401/404 via shared Error.
    • POST /api/valuation docs note each run persists a history row.
    • Added reference page and nav entry.

Summary by CodeRabbit

  • New Features

    • Added an API endpoint to retrieve catalog valuation history, with results ordered from newest to oldest.
    • Added support for limiting returned valuation records, up to 100 entries.
    • Valuation results now document that each run is saved to catalog history.
  • Documentation

    • Added the Catalog Valuations API reference page.
    • Updated navigation for catalog valuation and card-on-file subscription documentation.