Catalog Songs API

Retrieve songs within a specific catalog. Use GET to list catalog songs with pagination. Use POST to batch add songs to a catalog by ISRC. Use DELETE to batch remove songs from a catalog by ISRC. This endpoint joins the catalog_songs table with catalogs, songs, song_artists, and accounts to provide comprehensive song information for a given catalog.

Endpoint

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

GET Parameters

Name	Type	Required	Description
catalog_id	string	Yes	The unique identifier of the catalog to query songs for
artistName	string	No	Optional. Filters songs to only include those with matching artist name
page	number	No	Page number for pagination (default: 1)
limit	number	No	Number of songs per page (default: 20, max: 100)

POST Parameters

Name	Type	Required	Description
songs	array of objects	Yes	Array of songs for batch updates
songs[].catalog_id	string	Yes	Catalog ID to which the song will be added
songs[].isrc	string	Yes	Song ISRC to associate to the catalog
songs[].name	string	No	Optional. Applied only if internal search cannot find valid info for ISRC
songs[].album	string	No	Optional. Applied only if internal search cannot find valid info for ISRC
songs[].notes	string	No	Optional. Applied only if internal search cannot find valid info for ISRC
songs[].artists	string[]	No	Optional array of artist names. Applied only if internal search lacks info

DELETE Parameters

Name	Type	Required	Description
songs	array of objects	Yes	Array of songs for batch deletes
songs[].catalog_id	string	Yes	Catalog ID from which the song will be removed
songs[].isrc	string	Yes	Song ISRC to remove from the catalog

Behavior (DELETE)

Deletes the relationship in catalog_songs for each {catalog_id, isrc} pair.
If either catalog_id or isrc is missing in any item, an error is returned.
Request accepts a bulk array under songs.
Response structure is identical to GET and POST (songs array with pagination when applicable).

Request Examples

cURL

curl -X GET "https://api.recoupable.com/api/catalogs/songs?catalog_id=YOUR_CATALOG_ID&artistName=Queen&page=1&limit=20" \
  -H "Content-Type: application/json"

Response Format

The API returns JSON responses with song data including associated artist information and pagination metadata:

{
  "status": "success",
  "songs": [
    {
      "catalog_id": "YOUR_CATALOG_ID",
      "isrc": "USRC17607839",
      "name": "Bohemian Rhapsody",
      "album": "A Night at the Opera",
      "lyrics": "Is this the real life? Is this just fantasy? Caught in a landslide, no escape from reality...",
      "updated_at": "2024-03-06T15:33:27Z",
      "artists": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Queen",
          "timestamp": 1640995200000
        }
      ]
    },
    {
      "catalog_id": "YOUR_CATALOG_ID",
      "isrc": "USRC17607840",
      "name": "We Will Rock You",
      "album": "News of the World",
      "lyrics": "Buddy, you're a boy, make a big noise, playing in the street, gonna be a big man someday...",
      "updated_at": "2024-03-05T18:22:15Z",
      "artists": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Queen",
          "timestamp": 1640995200000
        }
      ]
    }
  ],
  "pagination": {
    "total_count": 42,
    "page": 1,
    "limit": 20,
    "total_pages": 3
  }
}

Response Properties

Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
songs	array	Array of song objects with artist information
pagination	object	Pagination metadata for the response
error	string	Error message (only present if status is "error")

Song Object

Property	Type	Description
isrc	string	International Standard Recording Code (primary key)
name	string	Name of the song
album	string	Name of the album the song belongs to
lyrics	string	Full lyrics of the song
updated_at	string	ISO timestamp of when the song data was last updated
artists	array	Array of artist objects associated with this song
artists[].id	string	Unique identifier for the artist account
artists[].name	string	Name of the artist (can be null)
artists[].timestamp	number	Timestamp associated with the artist account (can be null)
catalog_id	string	Catalog ID this song entry is associated with

Pagination Object

Property	Type	Description
total_count	number	Total number of songs in the catalog
page	number	Current page number
limit	number	Number of songs per page
total_pages	number	Total number of pages available

Database Schema

This endpoint queries the following database tables:

Catalog Songs Table

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

Catalogs Table

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

Songs Table

Primary Key: isrc (text)
Fields: name, album, lyrics, updated_at
Indexes: On name and album fields for performance

Song Artists Table

Primary Key: id (uuid)
Foreign Keys:
- song references songs.isrc
- artist references accounts.id