API REFERENCE

Add Catalog Songs

On this page

POST/api/catalogs/songs

Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/catalogs/songs' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "songs": [
    {
      "catalog_id": "YOUR_ID",
      "isrc": "string"
    }
  ]
}'

Request body required

Array of songs to add to catalog

application/json

songsarray<AddCatalogSongInput>required

Array of songs for batch updates

Item properties

catalog_idstringrequired

Catalog ID to which the song will be added

format: uuid

isrcstringrequired

Song ISRC to associate to the catalog

namestring

Optional. Applied only if internal search cannot find valid info for ISRC

albumstring

Optional. Applied only if internal search cannot find valid info for ISRC

notesstring

Optional. Applied only if internal search cannot find valid info for ISRC

artistsarray<string>

Optional array of artist names. Applied only if internal search lacks info

Item properties

string

Responses

200Songs added to catalog 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 required fields

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

Full specification

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

Download releases.json

View operation source

json

{
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "description": "Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.",
  "requestBody": {
    "description": "Array of songs to add to catalog",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddCatalogSongsRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Songs added to catalog successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required fields",
      "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"
          }
        }
      }
    }
  }
}