Catalogs API

Retrieve and manage catalogs associated with a specific account. Use GET to list catalogs linked to an account. Use POST to create a new catalog or link an existing catalog to an account. Use DELETE to unlink catalogs from an account and automatically remove orphaned catalogs (including cascading deletes of related catalog_songs) when no accounts remain linked; otherwise only the relationship is removed. The endpoint joins account_catalogs with catalogs to return catalog metadata for the specified account.

Endpoint

GET https://api.recoupable.com/api/catalogs
POST https://api.recoupable.com/api/catalogs
DELETE https://api.recoupable.com/api/catalogs

GET Parameters

Name	Type	Required	Description
account_id	string	Yes	The unique identifier of the account to query

POST Parameters

Name	Type	Required	Description
catalogs	array of objects	Yes	Array of catalog inputs for bulk create/link operations
catalogs[].account_id	string	Yes	The account to associate the catalog with
catalogs[].name	string	No	Catalog name to create if catalog_id is omitted
catalogs[].catalog_id	string	No	Existing catalog ID to link to the account

Behavior (POST)

If catalogs[].catalog_id is provided, links the existing catalog to the account (no new catalog created).
If catalogs[].name is provided and catalogs[].catalog_id is omitted, creates a new catalog then links it to the account.
If both catalogs[].name and catalogs[].catalog_id are provided, catalogs[].catalog_id takes priority.
If a provided catalogs[].catalog_id is invalid, an error is returned (even if catalogs[].name is provided).
Only if catalogs[].name is provided and catalogs[].catalog_id is omitted is a new catalog record created.

DELETE Parameters

Name	Type	Required	Description
catalogs	array of objects	Yes	Array of catalog-account pairs to remove
catalogs[].catalog_id	string	Yes	Catalog ID to remove
catalogs[].account_id	string	Yes	Account ID whose relationship will be removed

Behavior (DELETE)

Removes the relationship in account_catalogs for each {catalog_id, account_id} pair.
After removal, if no account_catalogs records remain for a catalog_id, the catalog is deleted from catalogs (cascades delete of related catalog_songs).
If other account_catalogs records remain for a catalog_id, only the relationship is removed; the catalog remains for other accounts.
If either catalog_id or account_id is missing in any item, an error is returned.
Request accepts a bulk array under catalogs.

Request Examples

cURL

curl -X GET "https://api.recoupable.com/api/catalogs?account_id=YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json"

Response Format

The API returns JSON responses with catalog data:

{
  "status": "success",
  "catalogs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Main Catalog",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-06T15:33:27Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "Archive Catalog",
      "created_at": "2024-02-01T14:20:00Z",
      "updated_at": "2024-03-05T18:22:15Z"
    }
  ]
}

Response Properties

Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
catalogs	array	Array of catalog objects
error	string	Error message (only present if status is "error")

Catalog Object

Property	Type	Description
id	string	Unique identifier for the catalog
name	string	Name of the catalog
created_at	string	ISO timestamp of when the catalog was created
updated_at	string	ISO timestamp of when the catalog was last updated

Database Schema

This endpoint queries the following database tables:

Catalogs Table

Primary Key: id (uuid)
Fields: name, created_at, updated_at
Indexes: On name and created_at fields for performance

Account Catalogs Table

Primary Key: id (uuid)
Foreign Keys:
- account references accounts.id
- catalog references catalogs.id
Unique Constraint: Combination of account and catalog
Indexes: On account, catalog, and created_at fields for performance

Usage Examples

Get all catalogs for a specific account

curl -X GET "https://api.recoupable.com/api/catalogs?account_id=550e8400-e29b-41d4-a716-446655440000"

Error Handling

The API uses conventional HTTP response codes:

200: Success
400: Bad Request (missing or invalid account_id)
401: Unauthorized
404: Account not found or no catalogs found
500: Internal Server Error

Example error response:

{
  "status": "error",
  "error": "Account not found"
}

Notes

The account_id parameter is required and must be a valid UUID
Catalogs are returned in descending order of creation (latest first)
Each catalog includes only the essential catalog information
All timestamps are returned in ISO 8601 format
The relationship between accounts and catalogs is many-to-many
Results include only the catalog metadata (id, name, created_at, updated_at)
POST returns the same format as GET (the catalogs list for the specified account_id).
If catalog_id is provided, links the existing catalog to the account (no new catalog created).
If name is provided and catalog_id is omitted, creates a new catalog and links it to the account.
If both are provided, catalog_id takes priority.
If a provided catalog_id is invalid, an error is returned (even if name is provided).