Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.patchline.ai/llms.txt

Use this file to discover all available pages before exploring further.

Human-readable reference for Patchline’s stable public MCP tools. For the exact current schema, connect an MCP client to https://www.patchline.ai/api/mcp/v1 and run tools/list. That MCP response is the machine-readable source of truth.   All tools are accessible on every tier; some are gated by tier limits (see per-tool notes).

​
Dispatch

The most-important tool. Always call this first when a user pastes a streaming URL. Arguments: url: string (required) — Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram URL of any kind. Returns: Canonical identity (type, id, name, platform) plus a ranked list of nextSteps — exact tool names with exact argument values. Example call: 
{
  "name": "analyze_url",
  "arguments": {
    "url": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"
  }
}
Example return: 
{
  "type": "track",
  "id": "4iV5W9uYEdYUVa79Axb7Rh",
  "isrc": "GBUM71029604",
  "name": "Bohemian Rhapsody",
  "artist": "Queen",
  "platform": "spotify",
  "nextSteps": [
    { "tool": "get_song_intelligence", "args": { "spotify_url": "..." } },
    { "tool": "get_audio_features",     "args": { "isrc": "GBUM71029604" } }
  ]
}

​
Catalog

Common arguments: page: int (default 1), pageSize: int (default 20, max 50). Arguments: query: string (free text), limit: int (default 10). Common arguments: assetId: string (the Patchline asset ID), mode: "summary" | "full".

​
Artists & roster

Common arguments: artist_name: string (required), mode: "summary" | "full". Arguments: query: string (artist name fragment). Common arguments: genre: string (optional), min_monthly_listeners: int, max_monthly_listeners: int, limit: int. Common arguments: artist_url: string (required — Spotify, YouTube, TikTok, SoundCloud, Apple Music, or Instagram), artist_name: string (optional display hint). Gated by: roster tier limit (Free 1 / Starter 1 / Pro 5 / Scale 20 / Enterprise unlimited). Common arguments: artist_id: string.

​
Releases

Arguments: status: string (optional — in_progress / scheduled / released / archived), limit: int (default 10).

​
Playlists

Common arguments: assetId: string (preferred catalog track), spotifyUrl: string (optional), limit: int. Gated by: required. Common arguments: playlist_url: string (Spotify playlist ID or URL), include_tracks: bool, include_curator_network: bool. Gated by: required. Common arguments: assetId: string, title: string (optional), enabledSections (optional section toggles).

​
Music Data

Common arguments: assetId: string (preferred), isrc: string, or spotifyTrackUrl: string. Common arguments: assetId: string, isrc: string, or spotifyTrackUrl: string; optional mode: "summary" | "full". Common arguments: spotifyId, spotifyTrackUrl, isrc, songName, or artistName.

​
AI Generation

Common arguments: artist_name: string. Note: Returns cached bio from intelligence enrichment. No live LLM call. Free. Common arguments: artist_name: string, track_name: string (optional), target_playlist: string (optional).

​
Common patterns

​
”User pasted a URL — what do I do?”

Always:
  1. Call analyze_url with the URL.
  2. Read the returned nextSteps.
  3. Call those tools with the exact arguments provided.
This pattern saves 2-3 round-trips vs. trying to guess what the URL is.

​
”User wants to add an artist by name”

Reject. The MCP tool reflects this: 
"add_artist" requires a `url` argument — a Spotify, YouTube, TikTok,
SoundCloud, Apple Music, or Instagram URL. Name-only is rejected
because many artists share names.
Use search_artists to find a candidate URL, then add_artist.

​
”User asks about a track that’s not in their catalog”

Two options:
  • Use analyze_url if they shared a URL — gets you the metadata without importing.
  • Recommend they import or upload the track. Once imported, all catalog tools work on it.

​
Rate limits

In practice, you’ll hit AI-credit limits before MCP rate limits. The server enforces sane per-user limits to prevent abuse but doesn’t publish hard rate-limit numbers.

​
Source of truth

  • This page is the human-readable guide for stable public behavior.
  • The MCP server’s tools/list response is the exact current machine-readable schema.
  • Client implementations should avoid caching schemas permanently.