API REFERENCE

Get Catalog Songs

On this page

GET/api/catalogs/songs

Retrieve songs within a specific catalog with pagination support. This endpoint joins catalog_songs with songs, song_artists, and accounts to provide comprehensive song information for a given catalog.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/catalogs/songs?catalog_id=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

Query parameters

catalog_idstringrequired

The unique identifier of the catalog to query songs for

artistNamestring

Optional. Filters songs to only include those with matching artist name

pageinteger

Page number for pagination (default: 1)

Default: 1

limitinteger

Number of songs per page (default: 20, max: 100)

Default: 20

Responses

200Catalog songs retrieved successfully

application/json

statusstring · enum

Status of the request

Values: "success", "error"

songsarray<CatalogSong>

Array of song objects with artist information

Item properties

catalog_idstring

Catalog ID this song entry is associated with

format: uuid

isrcstring

International Standard Recording Code (primary key)

namestring

Name of the song

albumstring

Name of the album the song belongs to

lyricsstring

Full lyrics of the song

updated_atstring

ISO timestamp of when the song data was last updated

format: date-time

artistsarray<SongArtist>

Array of artist objects associated with this song

Item properties

idstring

Unique identifier for the artist account

format: uuid

namestringnullable

Name of the artist (can be null)

timestampintegernullable

Timestamp associated with the artist account (can be null)

paginationobject

Pagination metadata for the response

Properties

total_countinteger

Total number of songs in the catalog

pageinteger

Current page number

limitinteger

Number of songs per page

total_pagesinteger

Total number of pages available

errorstring

Error message (only present if status is 'error')

400Bad request - missing or invalid catalog_id

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

403Forbidden - the catalog does not belong to the authenticated account

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

404Catalog not found or no songs in catalog

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

{
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "description": "Retrieve songs within a specific catalog with pagination support. This endpoint joins catalog_songs with songs, song_artists, and accounts to provide comprehensive song information for a given catalog.",
  "parameters": [
    {
      "name": "catalog_id",
      "in": "query",
      "description": "The unique identifier of the catalog to query songs for",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "artistName",
      "in": "query",
      "description": "Optional. Filters songs to only include those with matching artist name",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "page",
      "in": "query",
      "description": "Page number for pagination (default: 1)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 1
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Number of songs per page (default: 20, max: 100)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 20,
        "maximum": 100
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Catalog songs retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing or invalid catalog_id",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - the catalog does not belong to the authenticated account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Catalog not found or no songs in catalog",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    }
  }
}