API REFERENCE

Create Songs

On this page

POST/api/songs

Bulk create or fetch songs 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

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

Request

cURL

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

Request body required

Array of songs to create or fetch

application/json

songsarray<CreateSongInput>required

Array of song inputs for bulk create/fetch

Item properties

isrcstringrequired

International Standard Recording Code of the song to create or fetch

namestring

Optional. Song name, applied only if internal search cannot find valid info

albumstring

Optional. Album name, applied only if internal search cannot find valid info

notesstring

Optional. Notes for the song, applied only if internal search cannot find valid info

artistsarray<string>

Optional array of artist names, applied only if internal search cannot find valid info

Item properties

string

Responses

200Songs created or fetched successfully

application/json

statusstring · enum

Status of the request

Values: "success", "error"

songsarray<Song>

Array of song objects with artist information

Item properties

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

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

Full specification

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

Download releases.json

View operation source

json

{
  "description": "Bulk create or fetch songs 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 create or fetch",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSongsRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Songs created or fetched successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SongsErrorResponse"
          }
        }
      }
    }
  }
}