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

# Create 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.

<Note>
  This endpoint performs bulk create/fetch operations. 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/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/songs:
    post:
      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'
components:
  schemas:
    CreateSongsRequest:
      type: object
      required:
        - songs
      properties:
        songs:
          type: array
          items:
            $ref: '#/components/schemas/CreateSongInput'
          description: Array of song inputs for bulk create/fetch
    SongsResponse:
      type: object
      description: Response containing songs data
      properties:
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        songs:
          type: array
          items:
            $ref: '#/components/schemas/Song'
          description: Array of song objects with artist information
        error:
          type: string
          description: Error message (only present if status is 'error')
    SongsErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
          description: Status of the request
        error:
          type: string
          description: Error message describing what went wrong
    CreateSongInput:
      type: object
      required:
        - isrc
      properties:
        isrc:
          type: string
          description: International Standard Recording Code of the song to create or fetch
        name:
          type: string
          description: >-
            Optional. Song name, applied only if internal search cannot find
            valid info
        album:
          type: string
          description: >-
            Optional. Album name, applied only if internal search cannot find
            valid info
        notes:
          type: string
          description: >-
            Optional. Notes for the song, applied only if internal search cannot
            find valid info
        artists:
          type: array
          items:
            type: string
          description: >-
            Optional array of artist names, applied only if internal search
            cannot find valid info
    Song:
      type: object
      description: A song with its metadata and associated artists
      properties:
        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
        notes:
          type: string
          description: Notes for 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
    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)

````