> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Catalog 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.

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


## OpenAPI

````yaml post /api/catalogs/songs
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
security: []
paths:
  /api/catalogs/songs:
    post:
      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'
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)

````