# Create Songs

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

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.

## POST /api/songs

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

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[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/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)"
          }
        }
      }
    }
  }
}
```