docs(catalogs): v2 measurements contract — artist_account_id filter + echo + no-cap semantics

[sweetmantech]

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: feat(catalogs): GET /api/catalogs/measurements — per-ISRC latest playcounts + derived valuation band (chat#1850) api#757 (comment)) — 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).

Merge order

This docs PR merges first, 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

Updates the catalog measurements API contract to support artist-scoped reads and to echo the applied scope. Clarifies that results are exhaustive (no row cap) to better support v2 artist-scoped valuation.

• New Features
  • Optional artist_account_id (uuid) query param to scope results to songs linked to that artist; malformed values return 400.
  • New response field artist_account_id (uuid|null) echoes the applied scope so clients can verify before rendering.
  • measurements and total_streams now explicitly cover all matching songs with no row cap.

^{Written for commit c3392f0. Summary will update on new commits.}

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.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the OpenAPI specification for GET /api/catalogs/measurements to document optional artist_account_id scoping, clarify exhaustive/no-row-cap read behavior, expand 400 error documentation, and add a nullable artist_account_id field to the CatalogMeasurementsResponse schema.

Changes

Artist scoping documentation

Layer / File(s)	Summary
Endpoint parameter and error documentation api-reference/openapi/releases.json	Adds optional artist_account_id UUID query parameter, expands endpoint description for scoping and no-row-cap behavior, and updates the 400 response description to cover malformed artist_account_id.
Response schema updates api-reference/openapi/releases.json	Adds nullable artist_account_id field to CatalogMeasurementsResponse and clarifies measurements/total_streams field descriptions.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the OpenAPI contract update for catalog measurements, including the artist filter, echoed scope, and no-cap semantics.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/catalog-measurements-artist-filter

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

api-reference/openapi/releases.json (1)

2469-2482: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Consider marking artist_account_id (and other core fields) as required in the response schema.

The description explicitly tells clients to verify this echo before treating numbers as artist-scoped, but the schema has no required list, so the field is technically optional to omit. Adding artist_account_id to a required array (with nullable: true already in place) would make the contract clients are told to depend on enforceable in the spec itself.

♻️ Proposed schema tweak

       "CatalogMeasurementsResponse": {
         "type": "object",
         "description": "Latest per-song play counts for a catalog plus the valuation band derived from them",
+        "required": [
+          "status",
+          "measurements",
+          "valuation",
+          "total_streams",
+          "artist_account_id"
+        ],
         "properties": {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi/releases.json` around lines 2469 - 2482, The response
schema for the valuation payload should explicitly require the echoed scope
fields instead of leaving them optional. Update the OpenAPI schema around
artist_account_id so it is listed in the relevant required array (with nullable:
true preserved), and apply the same treatment to any other core response fields
that clients must always receive; use the existing schema object definitions in
the valuation response to keep the contract enforceable.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@api-reference/openapi/releases.json`:
- Around line 2469-2482: The response schema for the valuation payload should
explicitly require the echoed scope fields instead of leaving them optional.
Update the OpenAPI schema around artist_account_id so it is listed in the
relevant required array (with nullable: true preserved), and apply the same
treatment to any other core response fields that clients must always receive;
use the existing schema object definitions in the valuation response to keep the
contract enforceable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 109682cb-2c91-4476-9722-e887ca7f66a5

📥 Commits

Reviewing files that changed from the base of the PR and between 2cf8704 and c3392f0.

📒 Files selected for processing (1)

• api-reference/openapi/releases.json

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}