Skip to main content

Endpoints

Set these for the examples below:

export BASE_URL="https://www.songs2yt.com"   # or http://localhost:3000
export API_KEY="s2yt_live_your_key_here"

Upload a file (two-step)​

curl -X POST "$BASE_URL/api/v1/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@cover.jpg" \
  -F "type=image"
curl -X POST "$BASE_URL/api/v1/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@track1.mp3" \
  -F "type=audio"

Response includes path, filename, and size. Upload the image once, then each audio file. Keep the path values for the next step.

Use the exact path strings returned by upload. Add one items[] entry per track.

curl -X POST "$BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imagePath": "/uploads/.../cover.jpg",
    "items": [{
      "audioPath": "/uploads/.../track.mp3",
      "audioFilename": "track.mp3",
      "metadata": {
        "title": "My Track",
        "description": "",
        "tags": "electronic",
        "privacy": "PUBLIC",
        "categoryId": "10",
        "resolution": "1920x1080",
        "notifySubscribers": true,
        "madeForKids": false,
        "embeddable": true,
        "creativeCommons": false,
        "includeWatermark": false,
        "playlistId": null
      }
    }]
  }'

YouTube playlists (Pro)​

List existing playlists, create a new one, or create one inline when starting a job. Pass playlistId in item metadata / batch defaults, or use createPlaylist to make a playlist and attach all videos to it.

Privacy may be public, unlisted, or private. If playlist permission was just added, sign out and sign in again so OAuth includes youtube.force-ssl.

# List playlists
curl "$BASE_URL/api/v1/playlists" \
  -H "Authorization: Bearer $API_KEY"
# Create a playlist
curl -X POST "$BASE_URL/api/v1/playlists" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Album","description":"From Songs2YT","privacy":"unlisted"}'
{
  "playlistId": "PLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Or create one inline with a job / batch request:

{
  "createPlaylist": {
    "title": "My Album",
    "description": "Uploaded via Songs2YT",
    "privacy": "private"
  },
  "defaults": { "privacy": "PUBLIC" },
  "items": [{ "title": "Track One" }]
}

One-shot batch (small packs only)​

Upload one cover image and a few audio files in a single multipart request. Not recommended for large batches — use two-step if you see FormData parse errors.

curl -X POST "$BASE_URL/api/v1/jobs/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -F "image=@cover.jpg" \
  -F "audio=@track1.mp3" \
  -F "audio=@track2.mp3" \
  -F 'metadata={"createPlaylist":{"title":"My Album","privacy":"unlisted"},"defaults":{"privacy":"PUBLIC"},"items":[{"title":"Track One"},{"title":"Track Two"}]}'

Optional metadata JSON supports defaults applied to every item and per-item overrides in items. Item order should match the order of audio files.

Poll job status​

curl "$BASE_URL/api/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $API_KEY"
curl "$BASE_URL/api/v1/jobs?limit=10" \
  -H "Authorization: Bearer $API_KEY"