From 2e9b46e53b16b977a1d0f47c800858904d312cb9 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 22 Apr 2026 00:53:45 +0530 Subject: [PATCH 1/4] docs: migrate GET /api/catalogs to /api/accounts/{id}/catalogs Move the account id from a query param to a path segment on the GET operation, drop the per-operation api.recoupable.com servers override so the page renders against recoup-api.vercel.app, and enumerate the full response code set the new handler emits (200, 400, 401, 403, 404, 500). POST and DELETE overrides stay on the legacy /api/catalogs path until their own migrations land. --- api-reference/openapi/releases.json | 49 ++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 4a21d38e..66312e3a 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -851,18 +851,13 @@ } } }, - "/api/catalogs": { + "/api/accounts/{id}/catalogs": { "get": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], "description": "Retrieve catalogs associated with a specific account. The endpoint joins account_catalogs with catalogs to return catalog metadata for the specified account.", "parameters": [ { - "name": "account_id", - "in": "query", + "name": "id", + "in": "path", "description": "The unique identifier of the account to query", "required": true, "schema": { @@ -883,7 +878,27 @@ } }, "400": { - "description": "Bad request - missing or invalid account_id", + "description": "Bad request - missing or invalid account id", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CatalogsErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized - missing or invalid authentication", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CatalogsErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden - caller lacks access to the target account", "content": { "application/json": { "schema": { @@ -893,7 +908,17 @@ } }, "404": { - "description": "Account not found or no catalogs found", + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CatalogsErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { @@ -903,7 +928,9 @@ } } } - }, + } + }, + "/api/catalogs": { "post": { "servers": [ { From b937301331396089bc90436e2b28dab6cfbdb573 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 22 Apr 2026 01:20:05 +0530 Subject: [PATCH 2/4] docs: remove legacy /api/catalogs path key entirely --- api-reference/openapi/releases.json | 84 ----------------------------- 1 file changed, 84 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 66312e3a..b46f1d22 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -930,90 +930,6 @@ } } }, - "/api/catalogs": { - "post": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], - "description": "Create new catalogs or link existing catalogs to an account. If catalog_id is provided, links the existing catalog. If name is provided without catalog_id, creates a new catalog. If both are provided, catalog_id takes priority.", - "requestBody": { - "description": "Array of catalogs to create or link", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateCatalogsRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Catalogs created or linked successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CatalogsResponse" - } - } - } - }, - "400": { - "description": "Bad request - invalid parameters or catalog_id not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CatalogsErrorResponse" - } - } - } - } - } - }, - "delete": { - "servers": [ - { - "url": "https://api.recoupable.com" - } - ], - "description": "Unlink catalogs from an account. If no other accounts are linked to a catalog after removal, the catalog is automatically deleted (cascading to catalog_songs). Otherwise, only the account-catalog relationship is removed.", - "requestBody": { - "description": "Array of catalog-account pairs to remove", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeleteCatalogsRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Catalogs unlinked successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CatalogsResponse" - } - } - } - }, - "400": { - "description": "Bad request - missing catalog_id or account_id", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CatalogsErrorResponse" - } - } - } - } - } - } - }, "/api/catalogs/songs": { "get": { "servers": [ From 2bb54c388a582fc40a0a7517adf7375f4bc02be0 Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 22 Apr 2026 01:23:46 +0530 Subject: [PATCH 3/4] fix(catalogs): point Get Catalogs MDX to migrated /api/accounts/{id}/catalogs path The releases.json no longer exposes GET /api/catalogs after migration, so the page was rendering empty. Update the frontmatter to reference the new account-scoped path in releases.json. --- api-reference/songs/catalogs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/songs/catalogs.mdx b/api-reference/songs/catalogs.mdx index 357d672d..60d787fe 100644 --- a/api-reference/songs/catalogs.mdx +++ b/api-reference/songs/catalogs.mdx @@ -1,6 +1,6 @@ --- title: Get Catalogs -openapi: get /api/catalogs +openapi: "/api-reference/openapi/releases.json GET /api/accounts/{id}/catalogs" --- From 98d7ecbd1dc2c8b7f14d3b2c652f4963380124cd Mon Sep 17 00:00:00 2001 From: Arpit Gupta Date: Wed, 22 Apr 2026 02:37:44 +0530 Subject: [PATCH 4/4] docs: remove unused POST/DELETE catalogs pages These MDX pages referenced the legacy /api/catalogs POST/DELETE operations that were removed from releases.json. The verbs have no live caller and are not scheduled for migration. Also drop the Note callout on the Get Catalogs page referencing them. --- api-reference/songs/catalogs-create.mdx | 8 -------- api-reference/songs/catalogs-delete.mdx | 8 -------- api-reference/songs/catalogs.mdx | 4 ---- docs.json | 2 -- 4 files changed, 22 deletions(-) delete mode 100644 api-reference/songs/catalogs-create.mdx delete mode 100644 api-reference/songs/catalogs-delete.mdx diff --git a/api-reference/songs/catalogs-create.mdx b/api-reference/songs/catalogs-create.mdx deleted file mode 100644 index b0d690ab..00000000 --- a/api-reference/songs/catalogs-create.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Create Catalogs -openapi: post /api/catalogs ---- - - - If `catalog_id` is provided, the existing catalog is linked to the account. If `name` is provided without `catalog_id`, a new catalog is created. If both are provided, `catalog_id` takes priority. - diff --git a/api-reference/songs/catalogs-delete.mdx b/api-reference/songs/catalogs-delete.mdx deleted file mode 100644 index 97547067..00000000 --- a/api-reference/songs/catalogs-delete.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Delete Catalogs -openapi: delete /api/catalogs ---- - - - When unlinking a catalog from an account, if no other accounts remain linked to the catalog, the catalog is automatically deleted (cascading to catalog_songs). Otherwise, only the account-catalog relationship is removed. - diff --git a/api-reference/songs/catalogs.mdx b/api-reference/songs/catalogs.mdx index 60d787fe..eae6d4b2 100644 --- a/api-reference/songs/catalogs.mdx +++ b/api-reference/songs/catalogs.mdx @@ -2,7 +2,3 @@ title: Get Catalogs openapi: "/api-reference/openapi/releases.json GET /api/accounts/{id}/catalogs" --- - - - The Catalogs API also supports POST for creating/linking catalogs and DELETE for unlinking catalogs. See the [Create Catalogs](/api-reference/songs/catalogs-create) and [Delete Catalogs](/api-reference/songs/catalogs-delete) endpoints. - diff --git a/docs.json b/docs.json index 997442ca..f9c0c005 100644 --- a/docs.json +++ b/docs.json @@ -158,8 +158,6 @@ "api-reference/songs/analyze", "api-reference/songs/analyze-presets", "api-reference/songs/catalogs", - "api-reference/songs/catalogs-create", - "api-reference/songs/catalogs-delete", "api-reference/songs/catalog-songs", "api-reference/songs/catalog-songs-add", "api-reference/songs/catalog-songs-delete"