API REFERENCE

Rename Catalog

On this page

PATCH/api/catalogs/{catalogId}

Rename a catalog. The only mutable field is the display name — catalog membership is managed through Add catalog songs and Remove catalog songs.

Catalogs created by Run valuation are named after the measured artist. Catalogs created before that shipped are all named Valuation Catalog — this endpoint is how you give them real names.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/catalogs/YOUR_CATALOG_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string"
}'

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 rename.

Request body required

The new catalog name.

application/json

namestringrequired

New display name for the catalog. Must not be empty.

minLength: 1

Responses

200Catalog renamed

application/json

statusstring · enumrequired

Status of the request

Values: "success"

catalogobjectrequired

A catalog with its metadata

Properties

idstring

Unique identifier for the catalog

format: uuid

namestring

Name of the catalog

created_atstring

ISO timestamp of when the catalog was created

format: date-time

updated_atstring

ISO timestamp of when the catalog was last updated

format: date-time

400Bad request - catalogId is not a valid UUID, or name is missing or empty

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": "Rename a catalog. The only mutable field is the display name — catalog membership is managed through [Add catalog songs](/api-reference/songs/catalog-songs-add) and [Remove catalog songs](/api-reference/songs/catalog-songs-delete).\n\nCatalogs created by [Run valuation](/api-reference/songs/valuation-run) are named after the measured artist. Catalogs created before that shipped are all named `Valuation Catalog` — this endpoint is how you give them real names.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "catalogId",
      "in": "path",
      "description": "ID of the catalog to rename.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "description": "The new catalog name.",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateCatalogRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Catalog renamed",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UpdateCatalogResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - catalogId is not a valid UUID, or name is missing or empty",
      "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"
          }
        }
      }
    }
  }
}