> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drain.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify

> Search for artists, get artist profiles, and fetch top tracks on Spotify.

# Spotify

**Base URL:** `https://drain.lat/api/v1/spotify`

<AccordionGroup>
  <Accordion title="GET /search" icon="magnifying-glass">
    Search for artists on Spotify by name.

    ```
    GET /api/v1/spotify/search
    ```

    <ParamField query="q" type="string" required>
      Artist name to search.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/search?q=drake" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://drain.lat/api/v1/spotify/search?q=drake", {
        headers: { "x-api-key": "YOUR_API_KEY" }
      });
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/search",
          params={"q": "drake"},
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    <ResponseField name="query" type="string">The search query used.</ResponseField>

    <ResponseField name="artists" type="array">
      <Expandable title="artist object">
        <ResponseField name="id" type="string">Spotify artist ID.</ResponseField>
        <ResponseField name="name" type="string">Artist name.</ResponseField>
        <ResponseField name="genres" type="string[]">List of genres.</ResponseField>
        <ResponseField name="followers" type="number">Follower count.</ResponseField>
        <ResponseField name="popularity" type="number">Popularity score (0-100).</ResponseField>
        <ResponseField name="avatarUrl" type="string">Artist image URL.</ResponseField>
        <ResponseField name="spotifyUrl" type="string">Link to Spotify artist page.</ResponseField>
      </Expandable>
    </ResponseField>

    ```json Response theme={null}
    {
      "query": "drake",
      "artists": [
        {
          "id": "3TVXtAsR1Inumwj472S9r4",
          "name": "Drake",
          "genres": ["canadian hip hop", "rap", "toronto rap"],
          "followers": 88000000,
          "popularity": 96,
          "avatarUrl": "https://i.scdn.co/image/...",
          "spotifyUrl": "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"
        }
      ],
      "scrapedAt": "2026-05-05T12:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /artist/:id" icon="user">
    Get a Spotify artist by their Spotify ID.

    ```
    GET /api/v1/spotify/artist/:id
    ```

    <ParamField path="id" type="string" required>
      Spotify artist ID (e.g. `3TVXtAsR1Inumwj472S9r4` for Drake).
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "id": "3TVXtAsR1Inumwj472S9r4",
      "name": "Drake",
      "genres": ["canadian hip hop", "rap", "toronto rap"],
      "followers": 88000000,
      "popularity": 96,
      "avatarUrl": "https://i.scdn.co/image/...",
      "spotifyUrl": "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4",
      "scrapedAt": "2026-05-05T12:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /artist/:id/tracks" icon="music">
    Get an artist's top 10 tracks.

    ```
    GET /api/v1/spotify/artist/:id/tracks
    ```

    <ParamField path="id" type="string" required>
      Spotify artist ID.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/tracks" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/tracks",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/tracks",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    <ResponseField name="artistId" type="string">Spotify artist ID.</ResponseField>

    <ResponseField name="tracks" type="array">
      <Expandable title="track object">
        <ResponseField name="id" type="string">Track ID.</ResponseField>
        <ResponseField name="name" type="string">Track name.</ResponseField>
        <ResponseField name="album" type="string">Album name.</ResponseField>
        <ResponseField name="albumArt" type="string">Album art URL.</ResponseField>
        <ResponseField name="durationMs" type="number">Track duration in milliseconds.</ResponseField>
        <ResponseField name="popularity" type="number">Popularity score (0-100).</ResponseField>
        <ResponseField name="previewUrl" type="string">30-second preview URL.</ResponseField>
        <ResponseField name="spotifyUrl" type="string">Link to the track on Spotify.</ResponseField>
      </Expandable>
    </ResponseField>

    ```json Response theme={null}
    {
      "artistId": "3TVXtAsR1Inumwj472S9r4",
      "tracks": [
        {
          "id": "2507CQMJ8xFZbFGSC9FXMX",
          "name": "God's Plan",
          "album": "Scorpion",
          "albumArt": "https://i.scdn.co/image/...",
          "durationMs": 198973,
          "popularity": 88,
          "previewUrl": "https://p.scdn.co/mp3-preview/...",
          "spotifyUrl": "https://open.spotify.com/track/2507CQMJ8xFZbFGSC9FXMX"
        }
      ],
      "scrapedAt": "2026-05-05T12:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /search/tracks" icon="music">
    Search for tracks on Spotify.

    ```
    GET /api/v1/spotify/search/tracks
    ```

    <ParamField query="q" type="string" required>
      Track name or search query.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/search/tracks?q=god%27s+plan" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://drain.lat/api/v1/spotify/search/tracks?q=god's+plan", {
        headers: { "x-api-key": "YOUR_API_KEY" }
      });
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/search/tracks",
          params={"q": "god's plan"},
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    <ResponseField name="query" type="string">The search query used.</ResponseField>

    <ResponseField name="tracks" type="array">
      <Expandable title="track object">
        <ResponseField name="id" type="string">Track ID.</ResponseField>
        <ResponseField name="name" type="string">Track name.</ResponseField>
        <ResponseField name="artists" type="array">List of artists with `id` and `name`.</ResponseField>
        <ResponseField name="album" type="string">Album name.</ResponseField>
        <ResponseField name="albumArt" type="string">Album art URL.</ResponseField>
        <ResponseField name="durationMs" type="number">Duration in milliseconds.</ResponseField>
        <ResponseField name="popularity" type="number">Popularity score (0-100).</ResponseField>
        <ResponseField name="previewUrl" type="string">30-second preview URL.</ResponseField>
        <ResponseField name="explicit" type="boolean">Whether the track is explicit.</ResponseField>
        <ResponseField name="spotifyUrl" type="string">Link to the track on Spotify.</ResponseField>
      </Expandable>
    </ResponseField>

    ```json Response theme={null}
    {
      "query": "god's plan",
      "tracks": [
        {
          "id": "6DCZcSspjsKoFjzjrWoCdn",
          "name": "God's Plan",
          "artists": [{ "id": "3TVXtAsR1Inumwj472S9r4", "name": "Drake" }],
          "album": "Scorpion",
          "albumArt": "https://...",
          "durationMs": 198973,
          "popularity": 88,
          "previewUrl": "https://...",
          "explicit": true,
          "spotifyUrl": "https://open.spotify.com/track/6DCZcSspjsKoFjzjrWoCdn"
        }
      ],
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /search/albums" icon="record-vinyl">
    Search for albums on Spotify.

    ```
    GET /api/v1/spotify/search/albums
    ```

    <ParamField query="q" type="string" required>
      Album name or search query.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/search/albums?q=scorpion" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://drain.lat/api/v1/spotify/search/albums?q=scorpion", {
        headers: { "x-api-key": "YOUR_API_KEY" }
      });
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/search/albums",
          params={"q": "scorpion"},
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "query": "scorpion",
      "albums": [
        {
          "id": "1ATL5GLyefJaxhQzSPVrLX",
          "name": "Scorpion",
          "artists": [{ "id": "3TVXtAsR1Inumwj472S9r4", "name": "Drake" }],
          "releaseDate": "2018-06-29",
          "totalTracks": 25,
          "coverUrl": "https://...",
          "spotifyUrl": "https://open.spotify.com/album/1ATL5GLyefJaxhQzSPVrLX"
        }
      ],
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /artist/:id/albums" icon="layer-group">
    Get an artist's albums and singles.

    ```
    GET /api/v1/spotify/artist/:id/albums
    ```

    <ParamField path="id" type="string" required>
      Spotify artist ID.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/albums" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/albums",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/albums",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "artistId": "3TVXtAsR1Inumwj472S9r4",
      "albums": [
        {
          "id": "1ATL5GLyefJaxhQzSPVrLX",
          "name": "Scorpion",
          "type": "album",
          "releaseDate": "2018-06-29",
          "totalTracks": 25,
          "coverUrl": "https://...",
          "spotifyUrl": "https://open.spotify.com/album/1ATL5GLyefJaxhQzSPVrLX"
        }
      ],
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /artist/:id/related" icon="users">
    Get artists related to a given artist.

    ```
    GET /api/v1/spotify/artist/:id/related
    ```

    <ParamField path="id" type="string" required>
      Spotify artist ID.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/related" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/related",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/artist/3TVXtAsR1Inumwj472S9r4/related",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "artistId": "3TVXtAsR1Inumwj472S9r4",
      "related": [
        {
          "id": "0Y5tJX1MQlPlqiwlOH1tJY",
          "name": "Travis Scott",
          "genres": ["rap", "trap"],
          "followers": 42000000,
          "popularity": 91,
          "avatarUrl": "https://...",
          "spotifyUrl": "https://open.spotify.com/artist/0Y5tJX1MQlPlqiwlOH1tJY"
        }
      ],
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /track/:id" icon="music">
    Get info for a single Spotify track.

    ```
    GET /api/v1/spotify/track/:id
    ```

    <ParamField path="id" type="string" required>
      Spotify track ID.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/track/6DCZcSspjsKoFjzjrWoCdn" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://drain.lat/api/v1/spotify/track/6DCZcSspjsKoFjzjrWoCdn", {
        headers: { "x-api-key": "YOUR_API_KEY" }
      });
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/track/6DCZcSspjsKoFjzjrWoCdn",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "id": "6DCZcSspjsKoFjzjrWoCdn",
      "name": "God's Plan",
      "artists": [{ "id": "3TVXtAsR1Inumwj472S9r4", "name": "Drake" }],
      "album": "Scorpion",
      "albumId": "1ATL5GLyefJaxhQzSPVrLX",
      "albumArt": "https://...",
      "releaseDate": "2018-06-29",
      "durationMs": 198973,
      "popularity": 88,
      "previewUrl": "https://...",
      "explicit": true,
      "spotifyUrl": "https://open.spotify.com/track/6DCZcSspjsKoFjzjrWoCdn",
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>

  <Accordion title="GET /album/:id" icon="compact-disc">
    Get a full album with tracklist.

    ```
    GET /api/v1/spotify/album/:id
    ```

    <ParamField path="id" type="string" required>
      Spotify album ID.
    </ParamField>

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://drain.lat/api/v1/spotify/album/1ATL5GLyefJaxhQzSPVrLX" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://drain.lat/api/v1/spotify/album/1ATL5GLyefJaxhQzSPVrLX", {
        headers: { "x-api-key": "YOUR_API_KEY" }
      });
      const data = await res.json();
      ```

      ```python Python theme={null}
      import requests

      res = requests.get(
          "https://drain.lat/api/v1/spotify/album/1ATL5GLyefJaxhQzSPVrLX",
          headers={"x-api-key": "YOUR_API_KEY"}
      )
      print(res.json())
      ```
    </CodeGroup>

    <ResponseField name="id" type="string">Album ID.</ResponseField>
    <ResponseField name="name" type="string">Album name.</ResponseField>
    <ResponseField name="type" type="string">Album type (`album`, `single`, `compilation`).</ResponseField>
    <ResponseField name="artists" type="array">List of artists.</ResponseField>
    <ResponseField name="releaseDate" type="string">Release date.</ResponseField>
    <ResponseField name="totalTracks" type="number">Total track count.</ResponseField>
    <ResponseField name="coverUrl" type="string">Album cover URL.</ResponseField>
    <ResponseField name="label" type="string">Record label.</ResponseField>
    <ResponseField name="popularity" type="number">Popularity score (0-100).</ResponseField>

    <ResponseField name="tracks" type="array">
      <Expandable title="track object">
        <ResponseField name="id" type="string">Track ID.</ResponseField>
        <ResponseField name="name" type="string">Track name.</ResponseField>
        <ResponseField name="trackNumber" type="number">Track number on album.</ResponseField>
        <ResponseField name="durationMs" type="number">Duration in milliseconds.</ResponseField>
        <ResponseField name="previewUrl" type="string">30-second preview URL.</ResponseField>
        <ResponseField name="explicit" type="boolean">Whether the track is explicit.</ResponseField>
        <ResponseField name="spotifyUrl" type="string">Link to the track.</ResponseField>
      </Expandable>
    </ResponseField>

    ```json Response theme={null}
    {
      "id": "1ATL5GLyefJaxhQzSPVrLX",
      "name": "Scorpion",
      "type": "album",
      "artists": [{ "id": "3TVXtAsR1Inumwj472S9r4", "name": "Drake" }],
      "releaseDate": "2018-06-29",
      "totalTracks": 25,
      "coverUrl": "https://...",
      "label": "Young Money",
      "popularity": 85,
      "tracks": [
        {
          "id": "6DCZcSspjsKoFjzjrWoCdn",
          "name": "God's Plan",
          "trackNumber": 1,
          "durationMs": 198973,
          "previewUrl": "https://...",
          "explicit": true,
          "spotifyUrl": "https://open.spotify.com/track/6DCZcSspjsKoFjzjrWoCdn"
        }
      ],
      "spotifyUrl": "https://open.spotify.com/album/1ATL5GLyefJaxhQzSPVrLX",
      "scrapedAt": "2026-05-08T10:00:00.000Z"
    }
    ```
  </Accordion>
</AccordionGroup>