POST /v1/playlists/:id/tracks/move

Move up to 100 tracks from playlist :id (the source) to another of your playlists in a single request.

For each track: it's added to the target playlist, and — only if that succeeds — removed from the source. A track that can't be added (privacy rule, already in the target, etc.) stays in the source playlist and is reported in errors.

Request

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

Path parameters

Parameter	Type	Description
`id`	string	The source 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 move
`targetPlaylistId`	string	Yes	Destination playlist ID — must be different from the source

Example

curl -X POST https://pub.finetuning.ai/v1/playlists/9b2f51e2-4c1a-4b8e-9d3e-2f7a8c641b05/tracks/move \
  -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"], "targetPlaylistId": "3f8c2d10-7e5b-4a92-b6d1-8e4f0a92c7d3"}'

Response

200 OK

{
  "data": {
    "moved": ["a4f6c1e9-2d3b-4c8a-9e5f-7b1d0c2a8e64"],
    "errors": [
      { "trackId": "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72", "error": "Cannot add private track to public playlist" }
    ]
  }
}

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

400 Bad Request

{
  "error": {
    "code": "MOVE_FAILED",
    "message": "Track already in playlist",
    "details": [
      { "trackId": "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72", "error": "Track already in playlist" }
    ]
  }
}

Response fields

Field	Type	Description
`data.moved`	string[]	Track IDs that were added to the target and removed from the source
`data.errors`	array	Per-item failures — omitted when every track was moved
`data.errors[].trackId`	string	The track ID that failed
`data.errors[].error`	string	Why it failed

Per-item error reasons

All the reasons from adding tracks apply, plus one move-specific case:

Added to target but not found in source playlist — the track landed in the target playlist, but wasn't actually in the source. The net effect is an add rather than a move.

Errors

Code	Status	Description
`VALIDATION_ERROR`	400	`trackIds` invalid (missing/empty/non-strings/over 100), `targetPlaylistId` missing, or target equals the source
`MOVE_FAILED`	400	None of the tracks could be moved — 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

POST /v1/playlists/:id/tracks/move

On this page