idonthavespotify

# I Don't Have Spotify - API Documentation for AI Agents

## Overview

I Don't Have Spotify is a service that converts music streaming links between different platforms. It accepts a link from one streaming service (Spotify, Apple Music, YouTube Music, Tidal, Deezer, SoundCloud, Qobuz, Bandcamp, Pandora, JioSaavn, Apple Podcasts) and returns equivalent links for all other supported platforms.

**Important Limitation**: Playlists are out of scope. Only individual tracks, albums, artists, and podcasts are supported.

## Base URL

Production: https://idonthavespotify.sjdonado.com
Local Development: http://localhost:3000

## Authentication

The public instance needs no login: web search and shared links are open to everyone. Programmatic `/api/search` calls are disabled there until API keys land, and they answer 403 with `auth: "api-key"`. Programmatic clients must target a self-hosted instance today, where search stays open.

## Abuse Protection

- The public instance leaves web search and shared links open; only `/api/search` is disabled there (403 with `auth: "api-key"`), without touching upstream services
- `GET /verify?next=<path>` is a browser-only route on the public instance: Cloudflare's bot check runs there, then it redirects to the same-origin `next` path; it is not an API
- No per-IP rate limiting in the app; floods die at the Cloudflare edge (Bot Fight Mode plus a Managed Challenge rule)
- Upstream service quotas are shared: prefer specific adapters to reduce load

## API Endpoints

### POST /api/search

Convert a streaming service link to equivalent links on other platforms.

**Required Query Parameters:**
- `v`: API version (must be "1")

**Request Body:**
```json
{
  "link": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh",
  "adapters": ["spotify", "appleMusic", "youTube", "deezer", "soundCloud"]
}
```

**Request Body Parameters:**
- `link` (required): Valid streaming service URL
- `adapters` (optional): Array of streaming services to include in response. If omitted, returns all supported services.

**Valid Adapters:**
- `spotify`: Spotify
- `appleMusic`: Apple Music
- `youTube`: YouTube Music
- `deezer`: Deezer
- `soundCloud`: SoundCloud
- `tidal`: Tidal (via the MusicBrainz fallback below)
- `qobuz`: Qobuz
- `bandcamp`: Bandcamp
- `pandora`: Pandora
- `jiosaavn`: JioSaavn
- `applePodcasts`: Apple Podcasts (podcast and show searches)
- `podcastFeed`: RSS feed URL (podcast and show searches only)
- `invidious`: Invidious, a privacy-friendly YouTube front end. The link is `https://redirect.invidious.io` plus the YouTube result's watch, playlist, or channel path, where the visitor picks a live instance. It is derived without an extra request, so it appears only when a YouTube link is present, pasted or found

**Supported URL Patterns:**

**Spotify:**
- https://open.spotify.com/track/[id]
- https://open.spotify.com/album/[id]
- https://open.spotify.com/artist/[id]
- https://open.spotify.com/episode/[id]
- https://open.spotify.com/show/[id]
- https://spotify.link/[id]

**Apple Music:**
- https://music.apple.com/[country]/album/[name]/[id]
- https://music.apple.com/[country]/song/[name]/[id]
- https://music.apple.com/[country]/artist/[name]/[id]

**YouTube Music:**
- https://music.youtube.com/watch?v=[id]
- https://youtube.com/watch?v=[id]
- https://youtu.be/[id]

**Tidal:**
- https://tidal.com/browse/track/[id]
- https://tidal.com/browse/album/[id]
- https://tidal.com/browse/artist/[id]

**Deezer:**
- https://www.deezer.com/track/[id]
- https://www.deezer.com/album/[id]
- https://www.deezer.com/artist/[id]

**SoundCloud:**
- https://soundcloud.com/[user]/[track]
- https://on.soundcloud.com/[id]

**Qobuz:**
- https://open.qobuz.com/track/[id]
- https://open.qobuz.com/album/[id]
- https://open.qobuz.com/artist/[id]

**Bandcamp:**
- https://[artist].bandcamp.com/track/[name]
- https://[artist].bandcamp.com/album/[name]

**Pandora:**
- https://www.pandora.com/artist/[name]/[id]
- https://www.pandora.com/playlist/[name]/[id]
- https://www.pandora.com/podcast/[name]/[id]

**Apple Podcasts:**
- https://podcasts.apple.com/[country]/podcast/[name]/id[id]
- https://podcasts.apple.com/[country]/podcast/[name]/id[id]?i=[episode-id]

**JioSaavn:**
- https://www.jiosaavn.com/song/[name]/[id]
- https://www.jiosaavn.com/album/[name]/[id]
- https://www.jiosaavn.com/artist/[name]/[id]
- https://www.jiosaavn.com/featured/[name]/[id]
- https://www.jiosaavn.com/playlist/[name]/[id]

**Google Music Share (parse-only, not a search target):**
- https://www.google.com/gasearch?...
- https://share.google/[id]

**Response Format:**
```json
{
  "id": "base64_encoded_id",
  "type": "song|album|artist|podcast|show",
  "title": "Track/Album/Artist Name",
  "description": "Artist Name · Song · Year",
  "image": "https://image-url.com/cover.jpg",
  "audio": "https://audio-preview-url.com/preview.mp3",
  "source": "https://original-link.com",
  "universalLink": "https://idonthavespotify.sjdonado.com?id=encoded_id",
  "links": [
    {
      "type": "spotify",
      "url": "https://open.spotify.com/track/id",
      "isVerified": true
    },
    {
      "type": "appleMusic",
      "url": "https://music.apple.com/album/name/id",
      "isVerified": true
    }
  ]
}
```

**Response Fields:**
- `id`: Unique identifier for this search result
- `type`: Content type (song, album, artist, podcast, show)
- `title`: Primary title of the content
- `description`: Additional descriptive text
- `image`: Cover art/thumbnail URL
- `audio`: Preview audio URL (when available, primarily from Spotify)
- `source`: Original input URL
- `universalLink`: Shareable app link that opens the web interface with this result
- `links`: Array of equivalent links on other platforms
- `links[].type`: Streaming service identifier
- `links[].url`: Direct link to content on that platform
- `links[].isVerified`: Whether the link has been verified as working

### GET /api/status

Check service health. The response names the per-service upstream budgets plus a timestamp; `gate.enabled` stays false while web search is open.

**Response:**
```json
{
  "serviceGuards": {
    "<service>": {
      "callsUsed": 0,
      "callsMax": 300,
      "windowResetsIn": 3600,
      "circuitOpen": false,
      "failures": 0
    }
  },
  "timestamp": "2024-01-01T00:00:00.000Z",
  "gate": {
    "enabled": false
  }
}
```

### POST /api/auth/request-code

Retired: answers 410. Email login is gone from the public instance.

### POST /api/auth/verify-code

Retired: answers 410. Email login is gone from the public instance.

## Error Responses

**400 Bad Request:**
```json
{
  "error": "Invalid link, field is required"
}
```

**400 Bad Request (Invalid API Version):**
```json
{
  "error": "Unsupported API version"
}
```

**403 Forbidden (public instance, API disabled):**
```json
{
  "error": "API search is disabled on the public instance.",
  "auth": "api-key"
}
```

**410 Gone (email login retired):**
```json
{
  "error": "Email login is retired."
}
```

**500 Internal Server Error:**
```json
{
  "error": "Something went wrong, please try again later."
}
```

## Content Types

The API supports these content types:

- **song**: Individual tracks/songs
- **album**: Music albums or EPs
- **artist**: Artist pages/profiles
- **podcast**: Individual podcast episodes
- **show**: Podcast series/shows

**Note**: Playlists are not currently supported.

## Example Usage

### Convert a Spotify track to all platforms (self-hosted instance; the public instance returns a Worker 403 after passing the edge challenge, while suspicious requests may receive a Managed Challenge):

```bash
curl -X POST "http://localhost:3000/api/search?v=1" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh"
  }'
```

### Convert to specific platforms only (self-hosted instance; the public instance returns a Worker 403 after passing the edge challenge, while suspicious requests may receive a Managed Challenge):

```bash
curl -X POST "http://localhost:3000/api/search?v=1" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "https://music.apple.com/us/album/bohemian-rhapsody/1440650428?i=1440650450",
    "adapters": ["spotify", "youTube", "deezer"]
  }'
```

### Check service status:

```bash
curl "https://idonthavespotify.sjdonado.com/api/status"
```

## Integration Tips for AI Agents

1. **Always include the API version**: The `v=1` query parameter is required
2. **Respect shared upstream quotas**: use specific adapters when possible; if links come back unverified or missing, retry later
3. **Validate URLs first**: Ensure the input URL matches one of the supported patterns
4. **Remember playlist limitation**: Don't attempt to convert playlist URLs
5. **Use specific adapters when possible**: Include only the platforms you need to reduce response size
6. **Check isVerified field**: Prioritize verified links in your responses
7. **Handle missing audio**: Not all content has preview audio available
8. **Universal links**: Use the `universalLink` field for shareable links that work across platforms
9. **Public instance API**: `/api/search` there answers 403 with `auth: "api-key"`; use a self-hosted instance for programmatic calls
10. **Web search is open**: no login, no cookies, no quota headers to honor

## Web Interface

The service also provides a web interface at the base URL where users can paste links directly. The web interface supports the same link types and returns an HTML response with the converted links. A share page (`/?id=<id>`) loads in two steps: the page itself carries the track's title, description, cover, and audio preview (also as Open Graph tags), and its service links arrive from a second request to `/?id=<id>&rows=1`, which returns only the HTML list of links.

## Source Code

The project is open source and available at: https://github.com/sjdonado/idonthavespotify

More agent context in sjdonado/idonthavespotify

One other file this repository gives its agents.