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.

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"
          }
        }
      }
    }
  }
}