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 Songs

On this page
GET/api/songs

Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/songs' \
  --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://recoup-api.vercel.app/api/songs'

Parameters

Query parameters

isrcstring

International Standard Recording Code to filter by specific song

artist_account_idstring

Artist account ID to filter songs by artist

Responses

200Songs retrieved successfully

application/json

statusstring · enum

Status of the request

Values: "success", "error"

songsarray<Song>

Array of song objects with artist information

Item properties for songs
isrcstring

International Standard Recording Code (primary key)

namestring

Name of the song

albumstring

Name of the album the song belongs to

notesstring

Notes for 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)

errorstring

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

400Bad request - invalid parameters

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

500Internal server error

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
{
  "description": "Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.",
  "parameters": [
    {
      "name": "isrc",
      "in": "query",
      "description": "International Standard Recording Code to filter by specific song",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "artist_account_id",
      "in": "query",
      "description": "Artist account ID to filter songs by artist",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Songs retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsErrorResponse"
          }
        }
      }
    }
  }
}