docs: POST /api/catalogs create-catalog contract

[sweetmantech]

What

Documents a new endpoint POST /api/catalogs — creates a catalog owned by the authenticated account, and optionally materializes it from a completed valuation run.

• Account from credentials, never the body. Owner is derived from the Privy bearer JWT or x-api-key. Closes the IDOR risk of letting a client name the account.
• from.snapshot_id materialization. When supplied, the snapshot's measured ISRCs become catalog_songs and the catalog is linked via account_catalogs — fixing the "catalog empty after sign-in" gap.
• Idempotent. Re-submitting the same snapshot returns the catalog already created for that run (no duplicates).

Contract

POST /api/catalogs

• Body: CreateCatalogRequest — { name?, from?: { snapshot_id } }; at least one of name/from required.
• 200 CreateCatalogResponse — { status, catalog, songs_added } (also the idempotent re-claim response).
• 400 (neither name nor from / bad snapshot_id), 401 (unauth), 403 (snapshot owned by another account), 404 (snapshot not found).

Files

• api-reference/openapi/releases.json — new path + 3 schemas (CreateCatalogRequest, CreateCatalogResponse, CatalogMaterializationSource); 124 insertions, 0 deletions (additive, re-validated parse).
• api-reference/songs/catalogs-create.mdx — frontmatter-only reference page.
• docs.json — nav entry under Songs & Catalogs.

Merge order

Part of recoupable/chat#1801, Phase 2. Docs merge first, then the api implementation PR (which links back here). The api endpoint matches this contract exactly.

🤖 Generated with Claude Code

---

Summary by cubic

Documents the new POST /api/catalogs endpoint to create a catalog and optionally materialize it from a completed measurement snapshot. Materialization is idempotent: sending the same snapshot returns the existing catalog.

• New Features
  • Added OpenAPI path for /api/catalogs with CreateCatalogRequest and CreateCatalogResponse; defined 200/400/401/403/404 responses; shortened operation summary to “Create a catalog.”
  • Flattened request to use root snapshot (UUID) instead of from.snapshot_id; removed CatalogMaterializationSource.
  • Cross-links: the snapshot field references “Create measurement job,” and that endpoint links back to “Create catalog.”
  • Added api-reference/songs/catalogs-create.mdx (frontmatter-only) and updated docs.json: renamed the "Releases" tab to "Catalog" and split "Songs" and "Catalogs" groups.

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

Summary by CodeRabbit

• New Features

  • Added a new POST /api/catalogs endpoint to create or idempotently re-materialize catalogs for the authenticated account, with optional catalog name and snapshot-based source.
  • Responses include creation status, the created catalog, and a count of songs added; error details are returned for invalid or missing snapshots.

• Documentation

  • Added an API reference page for the catalog creation endpoint.
  • Updated navigation to split Songs and Catalogs, and linked the new documentation page.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a POST /api/catalogs OpenAPI path operation with documented error responses, three new component schemas (CatalogMaterializationSource, CreateCatalogRequest, CreateCatalogResponse), a new MDX reference page, and a nav entry in docs.json.

Changes

Create Catalog endpoint and documentation

Layer / File(s)	Summary
OpenAPI endpoint and schemas api-reference/openapi/releases.json	Adds three new component schemas: CatalogMaterializationSource (snapshot-based source), CreateCatalogRequest (optional name and from), and CreateCatalogResponse (status, catalog, songs_added, optional error). Adds the POST /api/catalogs path operation with 200/400/401/403/404 responses.
Documentation page and nav registration api-reference/songs/catalogs-create.mdx, docs.json	Adds the Create Catalog reference page; registers it in docs.json under the Catalog → Catalogs nav group, restructuring the navigation from a single Songs & Catalogs group into separate Songs and Catalogs groups.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• recoupable/docs#153: Previously removed the POST /api/catalogs operation from releases.json; this PR re-adds it with new CreateCatalogRequest/Response schemas and expanded documentation.

Poem

🐇 Hop, hop, a catalog blooms today,
A snapshot turns to songs along the way.
Idempotent magic, the same call twice?
Returns the same catalog, clean and precise.
The rabbit declares: new endpoints delight! 🎵

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: documenting the POST /api/catalogs endpoint contract for creating a catalog.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/create-catalog-contract

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 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 2092-2104: The CreateCatalogRequest schema has a documented
constraint that at least one of name or from must be supplied, but this is not
enforced in the OpenAPI schema itself, allowing invalid empty objects. Add an
OpenAPI constraint to the schema definition to enforce this rule, such as adding
minProperties: 1 to ensure at least one property is present, or use oneOf/anyOf
to explicitly define the valid combinations of properties that satisfy the
documented requirement.

In `@api-reference/songs/catalogs-create.mdx`:
- Around line 6-8: The catalogs-create.mdx file contains a custom `<Note>` block
in the body content, but API reference MDX pages must remain frontmatter-only to
ensure endpoint documentation is auto-generated from the OpenAPI spec. Remove
the entire `<Note>` block (lines 6-8) that describes the owning account
credentials and snapshot behavior, keeping only the frontmatter configuration at
the top of the file.
- Line 3: The OpenAPI frontmatter on line 3 does not follow the required format.
The HTTP method should be uppercase and the entire path should be wrapped in
single quotes. Update the frontmatter from the current format to use uppercase
POST and wrap the method and path together in single quotes following the
documented `openapi: 'METHOD /path'` format.

🪄 Autofix (Beta)

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

Run ID: 6bf344e2-f0eb-4f04-83f9-0f446f84aa1a

📥 Commits

Reviewing files that changed from the base of the PR and between 2b7459a and 8414699.

📒 Files selected for processing (3)

• api-reference/openapi/releases.json
• api-reference/songs/catalogs-create.mdx
• docs.json

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Enforce the “name or from required” rule in the schema.

Line 2094 documents a required constraint, but the schema currently allows {}. Add an OpenAPI constraint so tooling and generated clients enforce the same rule.

Suggested schema fix

       "CreateCatalogRequest": {
         "type": "object",
         "description": "Request body for creating a catalog. At least one of name or from must be supplied. The owning account is taken from the request credentials, never from this body.",
+        "anyOf": [
+          { "required": ["name"] },
+          { "required": ["from"] }
+        ],
         "properties": {
           "name": {
             "type": "string",
             "description": "Optional. Display name for the catalog. If omitted when from is supplied, a name is derived from the source run."
           },
           "from": {
             "$ref": "`#/components/schemas/CatalogMaterializationSource`"
           }
         }
       },

🤖 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 2092 - 2104, The
CreateCatalogRequest schema has a documented constraint that at least one of
name or from must be supplied, but this is not enforced in the OpenAPI schema
itself, allowing invalid empty objects. Add an OpenAPI constraint to the schema
definition to enforce this rule, such as adding minProperties: 1 to ensure at
least one property is present, or use oneOf/anyOf to explicitly define the valid
combinations of properties that satisfy the documented requirement.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use the required OpenAPI frontmatter format.

Line 3 should follow the documented openapi: 'METHOD /path' format (uppercase method).

Suggested frontmatter adjustment

-openapi: post /api/catalogs
+openapi: 'POST /api/catalogs'

As per coding guidelines, “Include OpenAPI spec reference in API reference MDX frontmatter using format: openapi: 'METHOD /path'.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	openapi: post /api/catalogs
	openapi: 'POST /api/catalogs'

🤖 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/songs/catalogs-create.mdx` at line 3, The OpenAPI frontmatter
on line 3 does not follow the required format. The HTTP method should be
uppercase and the entire path should be wrapped in single quotes. Update the
frontmatter from the current format to use uppercase POST and wrap the method
and path together in single quotes following the documented `openapi: 'METHOD
/path'` format.

Source: Coding guidelines

[cubic-dev-ai]

2 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/releases.json">

<violation number="1" location="api-reference/openapi/releases.json:2092">
P2: The schema allows an empty object `{}` despite documenting that at least one of `name` or `from` must be supplied. Add an `anyOf` constraint to enforce this rule at the schema level, so generated clients and validation tooling reject invalid payloads:

```json
"anyOf": [
  { "required": ["name"] },
  { "required": ["from"] }
]
```</violation>
</file>

<file name="api-reference/songs/catalogs-create.mdx">

<violation number="1" location="api-reference/songs/catalogs-create.mdx:6">
P3: Remove the `<Note>` block; this page must stay frontmatter-only and the prose belongs in `openapi.json`.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The schema allows an empty object {} despite documenting that at least one of name or from must be supplied. Add an anyOf constraint to enforce this rule at the schema level, so generated clients and validation tooling reject invalid payloads:

"anyOf": [
  { "required": ["name"] },
  { "required": ["from"] }
]

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/releases.json, line 2092:

<comment>The schema allows an empty object `{}` despite documenting that at least one of `name` or `from` must be supplied. Add an `anyOf` constraint to enforce this rule at the schema level, so generated clients and validation tooling reject invalid payloads:

```json
"anyOf": [
  { "required": ["name"] },
  { "required": ["from"] }
]
```</comment>

<file context>
@@ -2003,6 +2075,58 @@
+          }
+        }
+      },
+      "CreateCatalogRequest": {
+        "type": "object",
+        "description": "Request body for creating a catalog. At least one of name or from must be supplied. The owning account is taken from the request credentials, never from this body.",
</file context>

Suggested change

	"CreateCatalogRequest": {
	"type": "object",
	"description": "Request body for creating a catalog. At least one of name or from must be supplied. The owning account is taken from the request credentials, never from this body.",
	"CreateCatalogRequest": {
	"type": "object",
	"description": "Request body for creating a catalog. At least one of name or from must be supplied. The owning account is taken from the request credentials, never from this body.",
	"anyOf": [
	{ "required": ["name"] },
	{ "required": ["from"] }
	],

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
recoup-docs	🟢 Ready	View Preview	Jun 18, 2026, 1:47 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[sweetmantech]

KISS

Suggested change

"description": "Create a catalog owned by the authenticated account. The owning account is always derived from the request credentials (Privy bearer JWT or x-api-key) and never from the request body. Optionally materialize the catalog from a completed valuation run by passing `from.snapshot_id`: the snapshot's measured ISRCs are added as catalog songs and the catalog is linked to the account. Materialization is idempotent - re-submitting the same snapshot returns the catalog already created for that run instead of creating a duplicate.",

"description": "Create a catalog owned by the authenticated account. Optionally materialize the catalog from a completed valuation run by passing `from.snapshot_id`: the snapshot's measured ISRCs are added as catalog songs and the catalog is linked to the account. Materialization is idempotent - re-submitting the same snapshot returns the catalog already created for that run instead of creating a duplicate.",

[sweetmantech]

Applied in 70f75d1 — trimmed the description to your suggestion (dropped the redundant account-from-credentials sentence; the security schemes already convey it).

[sweetmantech]

KISS - too complex. follow existing docs architecture.

[sweetmantech]

Done in 70f75d1 — catalogs-create.mdx is now frontmatter-only (title + openapi), matching the sibling reference pages like catalogs.mdx. Removed the custom Note callout.

[sweetmantech]

DRY - add a hyperlink here for how to creat a playcount snapshot in the docs. Make it a 2-way reference, updating the playcount doc to also note this new doc.

[sweetmantech]

Done in c749f70. The snapshot field now links to Create measurement job, and that endpoint's description (in research.json) now links back to Create catalog — 2-way reference. (Also flattened from.snapshot_id → a root snapshot field per the other thread.)

[sweetmantech]

KISS

Suggested change

"description": "Create a catalog owned by the authenticated account. Optionally materialize the catalog from a completed valuation run by passing `snapshot` (the run's snapshot id): the snapshot's measured ISRCs are added as catalog songs and the catalog is linked to the account. Materialization is idempotent - re-submitting the same snapshot returns the catalog already created for that run instead of creating a duplicate.",

"description": "Create a catalog.",

[sweetmantech]

Applied in 9f211e2 — description is now just "Create a catalog.". The materialization + idempotency detail still lives in the snapshot field and the 200-response descriptions, so nothing's lost.