API Documentation

Authentication

The POST endpoint requires an API key. Send it in the x-api-key header, or as a bearer token via Authorization: Bearer <key>. The GET endpoint needs no key — share links are already public. To request an API key, contact the team.

Generate a playlist. Choose a mode and supply its parameters. Set "save": true to persist the result and receive a public share link.

Modes & parameters

Example request

curl -X POST https://www.foundational.art/api/public/playlists \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "mode": "ai",
    "vibe": "late-night listening room",
    "genres": ["jazz", "soul"],
    "mood": "warm",
    "minutes": 90,
    "save": true
  }'

Example response

200 OK

{
  "list": {
    "id": "ai-1719800000000",
    "title": "Late-Night Listening Room — Jul 1, 2026",
    "description": "A warm, slow-burning set of jazz and soul...",
    "source": "ai",
    "albums": [
      {
        "rank": 1,
        "album": "A Love Supreme",
        "artist": "John Coltrane",
        "appleAlbumId": "1452004704",
        "appleAlbumUrl": "https://music.apple.com/us/album/1452004704",
        "foundAlbum": "A Love Supreme",
        "foundArtist": "John Coltrane",
        "artwork": "https://.../{w}x{h}bb.jpg",
        "tracks": [
          {
            "id": "1452004707",
            "title": "Part 1: Acknowledgement",
            "artist": "John Coltrane",
            "trackNumber": 1,
            "discNumber": 1,
            "durationMs": 462000,
            "previewUrl": "https://.../preview.m4a"
          }
        ]
      }
    ]
  },
  "trackCount": 18,
  "shareId": "a1b2c3d4",
  "shareUrl": "https://www.foundational.art/p/a1b2c3d4"
}

shareId and shareUrl are only returned when "save": true is sent.

Error responses

Retrieve a previously-saved playlist by its share id. No API key required.

Example request

curl https://www.foundational.art/api/public/playlists?id=a1b2c3d4

Example response

200 OK

{
  "id": "a1b2c3d4",
  "list": {
    "id": "ai-1719800000000",
    "title": "Late-Night Listening Room — Jul 1, 2026",
    "description": "A warm, slow-burning set of jazz and soul...",
    "source": "ai",
    "albums": [ /* same shape as POST response */ ]
  },
  "shareUrl": "https://www.foundational.art/p/a1b2c3d4"
}

Error responses