docs(catalogs): GET /api/accounts/{id}/catalogs returns a valuation and an owner (chat#1943)

[sweetmantech]

Contract for both rows of chat#1943. The two features extend the same response, so the contract lands once rather than twice; the api implementation follows, then chat renders it.

What this documents

GET /api/accounts/{id}/catalogs now returns, per catalog, its estimated value and its owner.

Schema	Why it's new
CatalogListItem	The list item = Catalog + measured_song_count + valuation + owner. Deliberately not an extension of Catalog — that schema is shared by CreateCatalogResponse and UpdateCatalogResponse, which return the bare catalog and must not claim fields they don't send.
CatalogValuation	low / mid / high, same model as Get catalog measurements. Explicitly nullable: 34 of the 70 catalogs renamed in chat#1942 have no measured songs, and a client must render "not measured", never $0.
CatalogOwner	id, name, image, is_organization. name and image are nullable because account_info.image genuinely is for some accounts — the Recoup organization's is null — so clients fall back to initials instead of a broken image.

The decision worth reviewing

A catalog owned both directly and through an organization reports the organization. On prod today there are 135 account_catalogs links across 68 distinct owners, of which 1 is an organization, and 2 catalogs carry more than one owner link — so the tie-break is real, not hypothetical. The organization is the ownership worth surfacing to a member; showing "you" for a shared catalog would be the misleading half of the truth.

is_organization is a computed field, not a column: an owner is an organization when its id appears as organization_id in account_organization_ids, the inverse of the lookup getCatalogOwnerIds already does for visibility (chat#1938).

Files

• api-reference/openapi/releases.json — 3 new schemas, CatalogsResponse.catalogs repointed at CatalogListItem, and the operation description extended. 100 insertions, 3 deletions; re-parsed after the edit.

No new reference page or nav entry: this endpoint already has both.

Merge order

docs (this) → api → chat.

🤖 Generated with Claude Code

---

Summary by cubic

GET /api/accounts/{id}/catalogs now returns each catalog’s valuation band and owner so lists can be ranked by worth and clearly show ownership. Docs repoint the response to CatalogListItem and reuse ValuationBand for consistency with measurements.

• New Features
  • Response items now use CatalogListItem (catalog + measured_song_count + valuation + owner).
  • All CatalogListItem fields are required; valuation references ValuationBand and may be null when no songs are measured.
  • Added CatalogOwner (id, nullable name/image, is_organization; organization wins ties).

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

Summary by CodeRabbit

• Documentation
  • Updated the account catalogs API documentation to include estimated valuation ranges and ownership information.
  • Catalog list responses now document enriched catalog items with valuation and owner details.

[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

The OpenAPI specification now documents valuation and ownership metadata for account catalog list items. CatalogsResponse returns CatalogListItem objects with measured song counts, nullable valuation data, and owner details.

Changes

Catalog response contract

Layer / File(s)	Summary
Enriched catalog response schema api-reference/openapi/releases.json	Adds CatalogValuation, CatalogOwner, and CatalogListItem schemas. Updates the account catalogs endpoint description and changes CatalogsResponse.catalogs.items to CatalogListItem.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• /catalogs: add a valuation + owner avatar per card, and scope the list to the selected org app#1943 — Adds the OpenAPI contract for valuation and owner fields used by catalog card enhancements.

Possibly related PRs

• recoupable/docs#272 — Updates catalog valuation-related schemas in the same OpenAPI specification.
• recoupable/docs#288 — Updates the account catalogs endpoint documentation and response schema.

🚥 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 describes the endpoint documentation change for catalog valuation and ownership data.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/catalogs-list-valuation-owner

---

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]

Actionable comments posted: 1

🤖 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.
Inline comments:
In `@api-reference/openapi/releases.json`:
- Around line 3002-3043: Add a required array to the CatalogListItem schema
listing id, measured_song_count, valuation, and owner, while leaving the
existing property definitions unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f9f1dfc0-1aa2-46f2-9c6a-e6e4a3055bea

📥 Commits

Reviewing files that changed from the base of the PR and between f4a4bfe and 65f46c2.

📒 Files selected for processing (1)

• api-reference/openapi/releases.json

[cubic-dev-ai]

All reported issues were addressed across 1 file

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[sweetmantech]

Local render verification + bot triage

No hosted preview (Mintlify posts skipping on this repo), so I ran the docs locally from this branch at 2e87b63 — npx mintlify@latest dev — and drove the rendered page with Chrome DevTools.

The endpoint page

Checked	Result
Page resolves	/api-reference/songs/catalogs → 200, existing page, no nav change needed
Description	The added paragraph renders with valuation / owner.image inline-coded, right under the org-visibility text it extends
200 example	now shows measured_song_count, a full valuation object, and an owner object with is_organization
Response codes	200 / 400 / 401 / 403 / 404 / 500 — unchanged, nothing added or lost
Sibling pages	Create / Rename / Delete Catalog still render the bareCatalog — the point of keeping CatalogListItem separate

valuation renders as nullable, not optional

catalogs.valuation shows the type object | null — the oneOf wrapper survives Mintlify's renderer, which was the thing worth checking. A client reading this page cannot mistake "no band" for "field missing", which is what stops a card rendering $0 for the 34 unmeasured catalogs on prod.

The owner fields, with their required badges

owner.idstring<uuid>required, owner.namestring | null required, owner.imagestring | null required — nullable and required, which is exactly the distinction the review asked for and the one a generated client needs.

Bot findings — both valid, fixed in 2e87b63

1. cubic (P3): CatalogValuation duplicated the existing ValuationBand. Correct, and the better catch of the two. ValuationBand already exists, describes the same low/mid/high from the same model, and is already referenced by the measurements response — my schema was a second source of truth that had already drifted in prose ("10-16x" vs "10x/13x/16x"). Deleted; CatalogListItem.valuation now points at ValuationBand, so the docs state outright that a card and the report it opens return the same schema, not merely similar shapes. Net −25 lines.

2. CodeRabbit (Minor) + cubic (P3): CatalogListItem had no required array. Fixed — all seven properties are always present in the 200. valuation being nullable is not the same as optional, and a generated client would otherwise have treated id and owner as possibly absent.

One thing I did not change: ValuationBand itself still has no required array. That is pre-existing and shared with GET /api/catalogs/{id}/measurements, so tightening it belongs in its own PR rather than riding along here.

Not verifiable locally

llms.txt regeneration — mintlify dev serves the app shell for that path, so the new fields can only be confirmed in the generated text after the hosted build.

_{Screenshots live on the pr-assets/chat-1942 branch of this repo; keep it, or these review threads lose their images.}

🤖 Generated with Claude Code