# Add Catalog Songs

Source: https://recoupable.dev/docs/api-reference/songs/catalog-songs-add

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.

> **Note**
> 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.

## POST /api/catalogs/songs

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/catalogs/songs": {
      "post": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AddCatalogSongsRequest": {
        "type": "object",
        "required": [
          "songs"
        ],
        "properties": {
          "songs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddCatalogSongInput"
            },
            "description": "Array of songs for batch updates"
          }
        }
      },
      "CatalogSongsResponse": {
        "type": "object",
        "description": "Response containing catalog songs data with pagination",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "description": "Status of the request"
          },
          "songs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogSong"
            },
            "description": "Array of song objects with artist information"
          },
          "pagination": {
            "$ref": "#/components/schemas/CatalogSongsPagination",
            "description": "Pagination metadata for the response"
          },
          "error": {
            "type": "string",
            "description": "Error message (only present if status is 'error')"
          }
        }
      },
      "CatalogSongsErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "AddCatalogSongInput": {
        "type": "object",
        "required": [
          "catalog_id",
          "isrc"
        ],
        "properties": {
          "catalog_id": {
            "type": "string",
            "format": "uuid",
            "description": "Catalog ID to which the song will be added"
          },
          "isrc": {
            "type": "string",
            "description": "Song ISRC to associate to the catalog"
          },
          "name": {
            "type": "string",
            "description": "Optional. Applied only if internal search cannot find valid info for ISRC"
          },
          "album": {
            "type": "string",
            "description": "Optional. Applied only if internal search cannot find valid info for ISRC"
          },
          "notes": {
            "type": "string",
            "description": "Optional. Applied only if internal search cannot find valid info for ISRC"
          },
          "artists": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional array of artist names. Applied only if internal search lacks info"
          }
        }
      },
      "CatalogSong": {
        "type": "object",
        "description": "A song within a catalog with its metadata and associated artists",
        "properties": {
          "catalog_id": {
            "type": "string",
            "format": "uuid",
            "description": "Catalog ID this song entry is associated with"
          },
          "isrc": {
            "type": "string",
            "description": "International Standard Recording Code (primary key)"
          },
          "name": {
            "type": "string",
            "description": "Name of the song"
          },
          "album": {
            "type": "string",
            "description": "Name of the album the song belongs to"
          },
          "lyrics": {
            "type": "string",
            "description": "Full lyrics of the song"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the song data was last updated"
          },
          "artists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SongArtist"
            },
            "description": "Array of artist objects associated with this song"
          }
        }
      },
      "CatalogSongsPagination": {
        "type": "object",
        "description": "Pagination metadata for catalog songs response",
        "properties": {
          "total_count": {
            "type": "integer",
            "description": "Total number of songs in the catalog"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Number of songs per page"
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages available"
          }
        }
      },
      "SongArtist": {
        "type": "object",
        "description": "Artist associated with a song",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the artist account"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Name of the artist (can be null)"
          },
          "timestamp": {
            "type": "integer",
            "nullable": true,
            "description": "Timestamp associated with the artist account (can be null)"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```