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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

catalog_idquery · stringrequired

artistNamequery · string

pagequery · integer

limitquery · integer

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/catalogs/songs'

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