Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Get catalog songs

On this page
GET/api/catalogs/songs

Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.

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.

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

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/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, including an empty songs array and zero total count when no songs match.

application/json

statusstring · enum

Status of the request

Values: "success", "error"

songsarray<CatalogSong>

Array of song objects with artist information

Item properties for songs
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 for artists
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 for pagination
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')

Accessible catalog has no matching songs

empty
{
  "status": "success",
  "songs": [],
  "pagination": {
    "total_count": 0,
    "page": 1,
    "limit": 20,
    "total_pages": 0
  }
}

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 is missing or does not belong to the authenticated account or one of its organizations

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

500Server or database failure. Returns status: error and error: Internal server error.

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

500 example
{
  "status": "error",
  "error": "Internal server error"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json
View operation source
json
{
  "operationId": "getCatalogsSongs",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "description": "Retrieve songs in an accessible catalog with pagination. When a nonempty artistName is supplied, only songs with a matching artist name contribute to the results and total count. Without that filter, songs without a linked artist remain eligible. A successful query with no matching songs returns HTTP 200 with songs: [] and pagination.total_count: 0.",
  "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, including an empty songs array and zero total count when no songs match.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsResponse"
          },
          "examples": {
            "empty": {
              "summary": "Accessible catalog has no matching songs",
              "value": {
                "status": "success",
                "songs": [],
                "pagination": {
                  "total_count": 0,
                  "page": 1,
                  "limit": 20,
                  "total_pages": 0
                }
              }
            }
          }
        }
      }
    },
    "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 is missing or does not belong to the authenticated account or one of its organizations",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Server or database failure. Returns status: error and error: Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          },
          "example": {
            "status": "error",
            "error": "Internal server error"
          }
        }
      }
    }
  }
}

A successful query with no matching songs returns HTTP 200, an empty songs array, and pagination.total_count: 0. This also applies to an accessible catalog with no songs. An empty result is not a 404 response.

Use a nonempty artistName to request songs with a matching artist name. Omit the filter to include songs without a linked artist. Filtering applies before pagination and the total count; a client can use a zero count to decide whether to retry without the artist filter.

Missing or inaccessible catalogs return 403. A server or database failure returns 500 with status: "error" and error: "Internal server error".