POST /v1/playlists/:id/tracks

Add up to 100 tracks to one of your playlists in a single request.

Each track is checked individually (ownership, privacy, duplicates), so one bad ID doesn't fail the whole request — the response lists what was added plus a per-item errors array for anything that wasn't.

Request

POST https://pub.finetuning.ai/v1/playlists/:id/tracks

Path parameters

Parameter	Type	Description
`id`	string	The playlist ID (see GET /v1/playlists)

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`application/json`

Body

Field	Type	Required	Description
`trackIds`	string[]	Yes	1–100 track IDs to add

Example

curl -X POST https://pub.finetuning.ai/v1/playlists/9b2f51e2-4c1a-4b8e-9d3e-2f7a8c641b05/tracks \
  -H "X-API-Key: ft_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"trackIds": ["a4f6c1e9-2d3b-4c8a-9e5f-7b1d0c2a8e64", "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72"]}'

Response

200 OK

{
  "data": {
    "added": ["a4f6c1e9-2d3b-4c8a-9e5f-7b1d0c2a8e64"],
    "errors": [
      { "trackId": "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72", "error": "Track already in playlist" }
    ]
  }
}

When zero tracks could be added, the request returns 400 instead:

400 Bad Request

{
  "error": {
    "code": "ADD_FAILED",
    "message": "Cannot add private track to public playlist",
    "details": [
      { "trackId": "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72", "error": "Cannot add private track to public playlist" }
    ]
  }
}

Response fields

Field	Type	Description
`data.added`	string[]	Track IDs that were successfully added
`data.errors`	array	Per-item failures — omitted when every track was added
`data.errors[].trackId`	string	The track ID that failed
`data.errors[].error`	string	Why it failed

Per-item error reasons

These exact strings appear in errors[].error:

Playlist not found
Not authorized to modify this playlist
Track not found
Cannot add private track to public playlist
Cannot add others' tracks to private playlist
Track already in playlist

Privacy rules are enforced server-side and cannot be overridden via the API. Public playlists may only contain public tracks, and private playlists may only contain your own tracks. To add a private track to a public playlist, make the track public first in the web app.

Errors

Code	Status	Description
`VALIDATION_ERROR`	400	`trackIds` is missing, empty, contains non-strings, or has more than 100 items
`ADD_FAILED`	400	None of the tracks could be added — see `details` for per-item reasons
`MISSING_API_KEY`	401	X-API-Key header was not provided
`INVALID_API_KEY`	401	API key is malformed, revoked, or does not exist
`INTERNAL_ERROR`	500	Unexpected server error

On this page