Back

Public API & MCP Server

API & MCP Documentation

Foundational.Art exposes two programmatic interfaces: a public REST API at /api/public/playlists for generating and retrieving playlists, and an MCP server at /mcp so you can connect ChatGPT, Claude, Cursor, and other agents directly to the app.

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.

POST/api/public/playlists

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

modeparameters
ai{ vibe?, genres?[], mood?, minutes? }
theme{ theme, excludeTitles?[] }
artist{ artistId, artistName, artistMode?: "top10"|"obscure", excludeTitles?[] }
menu{ decades?[], excludeTitles?[] }
selection{ picks: [{ artist, track }] }
mood{ mood: { moodSummary, moodTags[], energy, valence }, intent: "match"|"lift" }

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

statusmeaning
400Invalid JSON, unknown mode, or missing required params
401Invalid or missing API key
422No tracks could be resolved
502List generated but saving failed (list still returned)
GET/api/public/playlists?id=<shareId>

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

statusmeaning
400Missing id query parameter
404Playlist not found
MCP/mcp

MCP Server

The Foundational.Art MCP server is published at https://www.foundational.art/mcp. It currently uses no authentication and exposes read-only tools for browsing and generating playlists.

Connecting an agent

  1. Open your agent's MCP / connector settings.
  2. Add a new MCP server with the URL https://www.foundational.art/mcp.
  3. Save — the agent fetches the tool manifest automatically.

Available tools

tooldescription
list_curated_playlistsList all curated Apple Music playlists with album and track counts. Input: none.
get_curated_playlistGet the full album and track listing for one curated playlist. Input: { id: string }.
generate_playlistGenerate a new playlist from the catalog. Input: { mode: "ai"|"theme"|"menu", vibe?, mood?, genres?[], minutes?, theme?, decades?[] }.

Example tool call

{
  "tool": "generate_playlist",
  "input": {
    "mode": "ai",
    "vibe": "late-night listening room",
    "genres": ["jazz", "soul"],
    "mood": "warm",
    "minutes": 90
  }
}

All current tools are read-only and idempotent — they return track metadata and generated lists without mutating any data.

Discovery / manifest

MCP clients can fetch the auto-generated manifest at /.lovable/mcp/manifest.json, which lists the server name, version, tools, and input schemas.

All responses are JSON and include permissive CORS headers, so the API can be called from the browser or any backend. For an API key or integration help, contact the team.