API REFERENCE

Delete Catalog

On this page

DELETE/api/catalogs/{catalogId}

Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).

The measurement that produced the catalog is not deleted. A playcount snapshot is a metered capture that spent credits and cannot be reproduced for a past date, while a catalog is a label over songs that can be rebuilt from it in one call — so deleting a catalog only clears the snapshot's reference to it. The snapshot then reads as unclaimed, and Create catalog can re-materialize it under a correct name. The released snapshot IDs are returned so that recovery does not require hunting for them.

Use this for genuine duplicates. To fix a catalog's name, use Rename catalog instead — it keeps the catalog's measurements and valuation history intact.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request DELETE \
  --url 'https://api.recoupable.dev/api/catalogs/YOUR_CATALOG_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

catalogIdpath · stringrequired

cURL for this request

curl --request DELETE \
  --url 'https://recoup-api.vercel.app/api/catalogs/{catalogId}'

Parameters

Path parameters

catalogIdstringrequired

ID of the catalog to delete.

Responses

200Catalog deleted

application/json

statusstring · enumrequired

Status of the request

Values: "success"

catalog_idstringrequired

ID of the deleted catalog

format: uuid

released_snapshot_idsarray<string>required

IDs of the playcount snapshots that pointed at this catalog. Those snapshots still exist - only their catalog reference was cleared - so each can be re-materialized into a new, correctly named catalog with Create catalog. Empty when the catalog was not created from a measurement run.

Item properties

string

400Bad request - catalogId is not a valid UUID

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

404Catalog not found - no catalog with this ID is visible to the caller. A catalog that exists but belongs to neither the authenticated account nor one of its organizations returns 404, not 403: the same visibility rule the catalog read paths use, so a catalog you cannot see is indistinguishable from one that does not exist.

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

500Internal server error

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json

View operation source

json

{
  "description": "Delete a catalog. Removes the catalog, its song membership (catalog_songs), its ownership links (account_catalogs) and its stored valuation history (catalog_valuations).\n\nThe measurement that produced the catalog is **not** deleted. A playcount snapshot is a metered capture that spent credits and cannot be reproduced for a past date, while a catalog is a label over songs that can be rebuilt from it in one call — so deleting a catalog only clears the snapshot's reference to it. The snapshot then reads as unclaimed, and [Create catalog](/api-reference/songs/catalogs-create) can re-materialize it under a correct name. The released snapshot IDs are returned so that recovery does not require hunting for them.\n\nUse this for genuine duplicates. To fix a catalog's name, use [Rename catalog](/api-reference/songs/catalog-rename) instead — it keeps the catalog's measurements and valuation history intact.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "catalogId",
      "in": "path",
      "description": "ID of the catalog to delete.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Catalog deleted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/DeleteCatalogResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - catalogId is not a valid UUID",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogsErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Catalog not found - no catalog with this ID is visible to the caller. A catalog that exists but belongs to neither the authenticated account nor one of its organizations returns 404, not 403: the same visibility rule the catalog read paths use, so a catalog you cannot see is indistinguishable from one that does not exist.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogsErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogsErrorResponse"
          }
        }
      }
    }
  }
}