docs: POST /api/catalogs create-catalog contract

Merged
SW
4mo ago
+126-4

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.

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.