Skip to content

docs(docs): migrate GET /api/accounts/{id}/catalogs #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 4 commits into from
Apr 23, 2026
Merged

docs(docs): migrate GET /api/accounts/{id}/catalogs #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2e9b46e
docs: migrate GET /api/catalogs to /api/accounts/{id}/catalogs
arpitgupta1214 Apr 21, 2026
b937301
docs: remove legacy /api/catalogs path key entirely
arpitgupta1214 Apr 21, 2026
2bb54c3
fix(catalogs): point Get Catalogs MDX to migrated /api/accounts/{id}/…
arpitgupta1214 Apr 21, 2026
98d7ecb
docs: remove unused POST/DELETE catalogs pages
arpitgupta1214 Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 14 additions & 71 deletions api-reference/openapi/releases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -851,18 +851,13 @@
}
}
},
"/api/catalogs": {
"/api/accounts/{id}/catalogs": {
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Comment on lines 853 to +854
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Confirm that no /api/catalogs path key remains and that the MDX pages still reference it.
echo "=== /api/catalogs occurrences in releases.json ==="
rg -n '"/api/catalogs"' api-reference/openapi/releases.json || echo "(none — legacy path fully removed)"

echo
echo "=== MDX pages still referencing legacy /api/catalogs ==="
rg -n --type=md --type-add 'mdx:*.mdx' --type=mdx '^openapi:.*\b/api/catalogs\b' api-reference || true

Repository: recoupable/docs

Length of output: 202

🏁 Script executed:

#!/bin/bash
# Find the actual MDX files and check their content
echo "=== Locating catalogs-create.mdx ==="
fd -name "catalogs-create.mdx" api-reference

echo
echo "=== Locating catalogs-delete.mdx ==="
fd -name "catalogs-delete.mdx" api-reference

echo
echo "=== Locating all catalogs-related mdx files ==="
fd -name "*catalogs*.mdx" api-reference

Repository: recoupable/docs

Length of output: 892

🏁 Script executed:

#!/bin/bash
# Find the actual MDX files and check their content
echo "=== Locating catalogs-related mdx files ==="
fd "catalogs.*\.mdx" api-reference

echo
echo "=== Searching for any mdx files in api-reference ==="
fd "\.mdx$" api-reference | head -20

Repository: recoupable/docs

Length of output: 974

🏁 Script executed:

#!/bin/bash
echo "=== Content of catalogs-create.mdx ==="
cat api-reference/songs/catalogs-create.mdx

echo
echo "=== Content of catalogs-delete.mdx ==="
cat api-reference/songs/catalogs-delete.mdx

echo
echo "=== Content of catalogs.mdx ==="
cat api-reference/songs/catalogs.mdx

Repository: recoupable/docs

Length of output: 1106

🏁 Script executed:

#!/bin/bash
# Check what operations exist on /api/accounts/{id}/catalogs in releases.json
echo "=== Checking /api/accounts/{id}/catalogs operations ==="
rg -A 200 '"/api/accounts/\{id\}/catalogs"' api-reference/openapi/releases.json | head -250

Repository: recoupable/docs

Length of output: 6431

🏁 Script executed:

#!/bin/bash
# Search for POST and DELETE operations on the accounts catalogs path
echo "=== Searching for POST on catalogs path ==="
rg -n '"post"' api-reference/openapi/releases.json | grep -i catalog

echo
echo "=== Searching for DELETE on catalogs path ==="
rg -n '"delete"' api-reference/openapi/releases.json | grep -i catalog

echo
echo "=== Full /api/catalogs search ==="
rg -n '/api/catalogs' api-reference/openapi/releases.json

echo
echo "=== Check if /api/accounts/{id}/catalogs has more than just get ==="
sed -n '/\/api\/accounts\/\{id\}\/catalogs/,/^    "\/api\//p' api-reference/openapi/releases.json | head -50

Repository: recoupable/docs

Length of output: 359

🏁 Script executed:

#!/bin/bash
# Final verification: check releases.json structure around accounts catalogs to confirm only GET exists
echo "=== Lines 850-900 of releases.json showing /api/accounts/{id}/catalogs ==="
sed -n '850,900p' api-reference/openapi/releases.json

Repository: recoupable/docs

Length of output: 1696

Removing the /api/catalogs path key breaks the Create Catalogs and Delete Catalogs doc pages.

This PR drops the entire /api/catalogs path key from releases.json, but api-reference/songs/catalogs-create.mdx still has openapi: post /api/catalogs and api-reference/songs/catalogs-delete.mdx still has openapi: delete /api/catalogs. With no matching operation in any mounted spec, Mintlify will render those two pages with only the title/description and no auto-generated request/response section — the exact failure mode that motivated commit 3 for catalogs.mdx.

The PR description also explicitly states POST and DELETE should remain on the legacy path until their own migrations land, so this removal appears unintended.

The new /api/accounts/{id}/catalogs path only includes the GET operation; POST and DELETE are entirely missing from the spec.

Two options to unbreak those pages before merge:

  1. Re-add the legacy /api/catalogs key with only the post and delete operations preserved (keep GET removed since it has moved).
  2. Migrate catalogs-create.mdx and catalogs-delete.mdx to reference the new account-scoped paths in the same PR (requires server-side routes to exist for POST/DELETE).

Option 1 matches the stated merge plan most closely.

🔧 Proposed fix — restore legacy path with POST/DELETE only 
+    "/api/catalogs": {
+      "post": { /* preserved POST operation spec */ },
+      "delete": { /* preserved DELETE operation spec */ }
+    },
     "/api/accounts/{id}/catalogs": {
       "get": {
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi/releases.json` around lines 853 - 854, Re-add the
legacy path key "/api/catalogs" to the OpenAPI spec in releases.json containing
only the post and delete operations (preserve their operation definitions and
schemas as they were) so api-reference/songs/catalogs-create.mdx and
catalogs-delete.mdx find matching operations; do not reintroduce GET (since that
moved to "/api/accounts/{id}/catalogs"), ensure the operationId, requestBody,
parameters and responses for POST and DELETE match the original definitions so
Mintlify can auto-generate the request/response sections for those docs.

"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": {
Expand All @@ -883,7 +878,7 @@
}
},
"400": {
"description": "Bad request - missing or invalid account_id",
"description": "Bad request - missing or invalid account id",
"content": {
"application/json": {
"schema": {
Expand All @@ -892,90 +887,38 @@
}
}
},
"404": {
"description": "Account not found or no catalogs found",
"401": {
"description": "Unauthorized - missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsErrorResponse"
}
}
}
}
}
},
"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",
"403": {
"description": "Forbidden - caller lacks access to the target account",
"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",
},
"404": {
"description": "Account not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsResponse"
"$ref": "#/components/schemas/CatalogsErrorResponse"
}
}
}
},
"400": {
"description": "Bad request - missing catalog_id or account_id",
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
Expand Down
8 changes: 0 additions & 8 deletions api-reference/songs/catalogs-create.mdx
View file
Open in desktop

This file was deleted.

8 changes: 0 additions & 8 deletions api-reference/songs/catalogs-delete.mdx
View file
Open in desktop

This file was deleted.

6 changes: 1 addition & 5 deletions api-reference/songs/catalogs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
---
title: Get Catalogs
openapi: get /api/catalogs
openapi: "/api-reference/openapi/releases.json GET /api/accounts/{id}/catalogs"
---

<Note>
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.
</Note>
2 changes: 0 additions & 2 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down