# Spotify Integration via LowCodeAPI

## Overview

Spotify is a music streaming service providing access to millions of songs and podcasts. The Spotify API provides comprehensive functionality for:

- **Tracks** - Get track information, audio features, and analysis
- **Albums** - Browse albums and get album details
- **Artists** - Get artist information and top tracks
- **Playlists** - Manage user playlists and tracks
- **Browse** - Explore categories, new releases, and recommendations
- **Search** - Search for music across all categories
- **User Profile** - Get user information and playback state
- **Player** - Control playback and manage devices

## Base Endpoint

```
https://api.lowcodeapi.com/spotify/
```

## Authentication

LowCodeAPI handles authentication automatically using OAuth2. You only need to:

1. **Create an app** at [Spotify Dashboard](https://developer.spotify.com/dashboard) to get your Client ID and Secret
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Spotify access token
- Apply it to each request as a Bearer token

**Auth Type**: OAuth2 (Bearer Token)

## API Categories

- **Music & Audio** - Music streaming and management

## Common Endpoints

### Category: Tracks

#### Get Track

**Method**: `GET` | **LowCodeAPI Path**: `/v1/tracks/id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/tracks/id?id={id}&api_token={api_token}
```

**Description**: Get details for a specific track.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Spotify track ID |
| `market` | string | No | ISO 3166-1 alpha-2 country code |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/tracks/id?id=3n3Ppam7vgaVa1iaRUc9Lp&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Track](https://developer.spotify.com/documentation/web-api/reference/get-track)

---

#### Get Audio Features for Track

**Method**: `GET` | **LowCodeAPI Path**: `/v1/audio-features/id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/audio-features/id?id={id}&api_token={api_token}
```

**Description**: Get audio features for a track (danceability, energy, tempo, etc.).

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Spotify track ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/audio-features/id?id=3n3Ppam7vgaVa1iaRUc9Lp&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Audio Features](https://developer.spotify.com/documentation/web-api/reference/get-audio-features-track)

---

#### Get Several Audio Features

**Method**: `GET` | **LowCodeAPI Path**: `/v1/audio-features`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/audio-features?ids={ids}&api_token={api_token}
```

**Description**: Get audio features for multiple tracks.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | string | Yes | Comma-separated list of track IDs |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/audio-features?ids=3n3Ppam7vgaVa1iaRUc9Lp,7qiZfU4dY1lWllzX7mPBIj&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Several Audio Features](https://developer.spotify.com/documentation/web-api/reference/get-several-audio-features)

---

### Category: Albums

#### Get Album

**Method**: `GET` | **LowCodeAPI Path**: `/v1/albums/id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/albums/id?id={id}&api_token={api_token}
```

**Description**: Get album details including tracks.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Spotify album ID |
| `market` | string | No | ISO 3166-1 alpha-2 country code |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/albums/id?id=4aawyAB9vmqN3uQ7FjRGTy&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Album](https://developer.spotify.com/documentation/web-api/reference/get-an-album)

---

#### Get Several Albums

**Method**: `GET` | **LowCodeAPI Path**: `/v1/albums`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/albums?ids={ids}&api_token={api_token}
```

**Description**: Get details for multiple albums.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | string | Yes | Comma-separated list of album IDs |
| `market` | string | No | ISO 3166-1 alpha-2 country code |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/albums?ids=4aawyAB9vmqN3uQ7FjRGTy,1A2GTWGtFfWp7KSQTwWOyo&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Several Albums](https://developer.spotify.com/documentation/web-api/reference/get-multiple-albums)

---

### Category: Artists

#### Get Artist

**Method**: `GET` | **LowCodeAPI Path**: `/v1/artists/id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/artists/id?id={id}&api_token={api_token}
```

**Description**: Get information about an artist.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Spotify artist ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/artists/id?id=0TnOYISbd1XYRBk9myaseg&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Artist](https://developer.spotify.com/documentation/web-api/reference/get-an-artist)

---

#### Get Artist Top Tracks

**Method**: `GET` | **LowCodeAPI Path**: `/v1/artists/id/top-tracks`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/artists/id/top-tracks?id={id}&api_token={api_token}
```

**Description**: Get an artist's top tracks in a country.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Spotify artist ID |
| `market` | string | Yes | ISO 3166-1 alpha-2 country code |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/artists/id/top-tracks?id=0TnOYISbd1XYRBk9myaseg&market=US&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Artist's Top Tracks](https://developer.spotify.com/documentation/web-api/reference/get-an-artists-top-tracks)

---

### Category: Playlists

#### Get Playlist

**Method**: `GET` | **LowCodeAPI Path**: `/v1/playlists/playlist_id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/playlists/playlist_id?playlist_id={playlist_id}&api_token={api_token}
```

**Description**: Get details and tracks for a playlist.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `playlist_id` | string | Yes | Spotify playlist ID |
| `market` | string | No | ISO 3166-1 alpha-2 country code |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/playlists/playlist_id?playlist_id=3cEYpjA9oz9GiIacDqBQ5I&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Playlist](https://developer.spotify.com/documentation/web-api/reference/get-playlist)

---

#### Get User Playlists

**Method**: `GET` | **LowCodeAPI Path**: `/v1/me/playlists`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me/playlists?api_token={api_token}
```

**Description**: Get current user's playlists.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of playlists (default: 20, max: 50) |
| `offset` | integer | No | Index of first playlist to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/me/playlists?api_token=YOUR_API_TOKEN&limit=50"
```

**Official Documentation**: [Get User Playlists](https://developer.spotify.com/documentation/web-api/reference/get-a-list-of-current-users-playlists)

---

#### Create Playlist

**Method**: `POST` | **LowCodeAPI Path**: `/v1/users/user_id/playlists`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/users/user_id/playlists?user_id={user_id}&api_token={api_token}
```

**Description**: Create a playlist for a user.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | User's Spotify ID |

**Request Body**:
```json
{
  "name": "My New Playlist",
  "description": "Created via API",
  "public": false
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Playlist name |
| `description` | string | No | Playlist description |
| `public` | boolean | No | Playlist visibility (default: true) |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/spotify/v1/users/user_id/playlists?user_id=YOUR_USER_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workout Mix 2024",
    "description": "High energy songs for workouts",
    "public": true
  }'
```

**Official Documentation**: [Create Playlist](https://developer.spotify.com/documentation/web-api/reference/create-playlist)

---

#### Add Items to Playlist

**Method**: `POST` | **LowCodeAPI Path**: `/v1/playlists/playlist_id/tracks`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/playlists/playlist_id/tracks?playlist_id={playlist_id}&api_token={api_token}
```

**Description**: Add tracks to a playlist.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `playlist_id` | string | Yes | Spotify playlist ID |
| `position` | integer | No | Position to insert tracks |
| `uris` | string | Yes | Comma-separated Spotify track URIs |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/spotify/v1/playlists/playlist_id/tracks?playlist_id=3cEYpjA9oz9GiIacDqBQ5I&uris=spotify:track:3n3Ppam7vgaVa1iaRUc9Lp,spotify:track:7qiZfU4dY1lWllzX7mPBIj&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Add Tracks to Playlist](https://developer.spotify.com/documentation/web-api/reference/add-tracks-to-playlist)

---

### Category: Browse

#### Get New Releases

**Method**: `GET` | **LowCodeAPI Path**: `/v1/browse/new-releases`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/browse/new-releases?api_token={api_token}
```

**Description**: Get new album releases.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string | No | ISO 3166-1 alpha-2 country code |
| `limit` | integer | No | Maximum number of items (default: 20) |
| `offset` | integer | No | Index of first item to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/new-releases?api_token=YOUR_API_TOKEN&limit=50"
```

**Official Documentation**: [Get New Releases](https://developer.spotify.com/documentation/web-api/reference/get-new-releases)

---

#### Get Featured Playlists

**Method**: `GET` | **LowCodeAPI Path**: `/v1/browse/featured-playlists`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/browse/featured-playlists?api_token={api_token}
```

**Description**: Get Spotify featured playlists.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locale` | string | No | Desired language and country combination |
| `country` | string | No | ISO 3166-1 alpha-2 country code |
| `timestamp` | string | No | Timestamp for featured playlists |
| `limit` | integer | No | Maximum number of items (default: 20) |
| `offset` | integer | No | Index of first item to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/featured-playlists?api_token=YOUR_API_TOKEN&limit=50"
```

**Official Documentation**: [Get Featured Playlists](https://developer.spotify.com/documentation/web-api/reference/get-featured-playlists)

---

#### Get Categories

**Method**: `GET` | **LowCodeAPI Path**: `/v1/browse/categories`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/browse/categories?api_token={api_token}
```

**Description**: Get list of Spotify categories.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locale` | string | No | Desired language |
| `country` | string | No | ISO 3166-1 alpha-2 country code |
| `limit` | integer | No | Maximum number of categories (default: 20) |
| `offset` | integer | No | Index of first category to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/categories?api_token=YOUR_API_TOKEN&limit=50"
```

**Official Documentation**: [Get Categories](https://developer.spotify.com/documentation/web-api/reference/get-categories)

---

### Category: Search

#### Search

**Method**: `GET` | **LowCodeAPI Path**: `/v1/search`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/search?q={q}&type={type}&api_token={api_token}
```

**Description**: Search for content across Spotify.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query |
| `type` | string | Yes | Item types: album, artist, playlist, track, show, episode |
| `market` | string | No | ISO 3166-1 alpha-2 country code |
| `limit` | integer | No | Maximum number of results (default: 20) |
| `offset` | integer | No | Index of first result to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/search?q=Beatles&type=album,artist,track&limit=50&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Search](https://developer.spotify.com/documentation/web-api/reference/search)

---

### Category: User Profile

#### Get Current User Profile

**Method**: `GET` | **LowCodeAPI Path**: `/v1/me`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me?api_token={api_token}
```

**Description**: Get current user's profile information.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/me?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Current User Profile](https://developer.spotify.com/documentation/web-api/reference/get-current-users-profile)

---

#### Get User Profile

**Method**: `GET` | **LowCodeAPI Path**: `/v1/users/user_id`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/users/user_id?user_id={user_id}&api_token={api_token}
```

**Description**: Get public profile information for a user.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Spotify user ID |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/users/user_id?user_id=exampleuser&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get User Profile](https://developer.spotify.com/documentation/web-api/reference/get-users-profile)

---

### Category: Player

#### Get Playback State

**Method**: `GET` | **LowCodeAPI Path**: `/v1/me/player`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me/player?api_token={api_token}
```

**Description**: Get current playback state.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `market` | string | No | ISO 3166-1 alpha-2 country code |
| `additional_types` | string | No | Additional types to return |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/me/player?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Playback State](https://developer.spotify.com/documentation/web-api/reference/get-information-about-the-users-current-playback)

---

#### Get Currently Playing Track

**Method**: `GET` | **LowCodeAPI Path**: `/v1/me/player/currently-playing`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me/player/currently-playing?api_token={api_token}
```

**Description**: Get currently playing track.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/spotify/v1/me/player/currently-playing?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Currently Playing Track](https://developer.spotify.com/documentation/web-api/reference/get-the-users-currently-playing-track)

---

#### Start/Resume Playback

**Method**: `PUT` | **LowCodeAPI Path**: `/v1/me/player/play`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me/player/play?api_token={api_token}
```

**Description**: Start or resume playback.

**Request Body**:
```json
{
  "context_uri": "spotify:album:4aawyAB9vmqN3uQ7FjRGTy",
  "offset": {
    "position": 5
  },
  "uris": ["spotify:track:3n3Ppam7vgaVa1iaRUc9Lp"]
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `context_uri` | string | No | Spotify URI to play |
| `uris` | array | No | Array of track URIs to play |
| `offset` | object | No | Starting position |
| `position_ms` | integer | No | Seek to position in milliseconds |

**Example Request**:
```bash
curl -X PUT "https://api.lowcodeapi.com/spotify/v1/me/player/play?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uris": ["spotify:track:3n3Ppam7vgaVa1iaRUc9Lp"]
  }'
```

**Official Documentation**: [Start/Resume Playback](https://developer.spotify.com/documentation/web-api/reference/start-a-users-playback)

---

#### Pause Playback

**Method**: `PUT` | **LowCodeAPI Path**: `/v1/me/player/pause`

**Full URL**:
```
https://api.lowcodeapi.com/spotify/v1/me/player/pause?api_token={api_token}
```

**Description**: Pause current playback.

**Example Request**:
```bash
curl -X PUT "https://api.lowcodeapi.com/spotify/v1/me/player/pause?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Pause Playback](https://developer.spotify.com/documentation/web-api/reference/pause-a-users-playback)

---

## Usage Examples

### Example 1: Search and Add to Playlist

Find songs and create a playlist:

```bash
# Step 1: Search for tracks
# No ID needed - searches across Spotify
curl -X GET "https://api.lowcodeapi.com/spotify/v1/search?q=rock+classics&type=track&limit=50&api_token=YOUR_API_TOKEN"

# Step 2: Get user ID for creating playlist
# No ID needed - gets current user profile
curl -X GET "https://api.lowcodeapi.com/spotify/v1/me?api_token=YOUR_API_TOKEN"

# Step 3: Create a new playlist
# Replace USER_ID with actual user ID from Step 2
curl -X POST "https://api.lowcodeapi.com/spotify/v1/users/user_id/playlists?user_id=USER_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rock Classics Collection",
    "public": true
  }'

# Step 4: Add tracks to playlist
# Replace PLAYLIST_ID with actual playlist ID from Step 3
curl -X POST "https://api.lowcodeapi.com/spotify/v1/playlists/playlist_id/tracks?playlist_id=PLAYLIST_ID&uris=spotify:track:TRACK_ID_1,spotify:track:TRACK_ID_2&api_token=YOUR_API_TOKEN"
```

### Example 2: Get Artist Information

Retrieve artist details and top tracks:

```bash
# Step 1: Get artist information
# No ID needed - gets artist by ID
curl -X GET "https://api.lowcodeapi.com/spotify/v1/artists/id?id=0TnOYISbd1XYRBk9myaseg&api_token=YOUR_API_TOKEN"

# Step 2: Get artist's top tracks
# No ID needed - uses same artist ID
curl -X GET "https://api.lowcodeapi.com/spotify/v1/artists/id/top-tracks?id=0TnOYISbd1XYRBk9myaseg&market=US&api_token=YOUR_API_TOKEN"
```

### Example 3: Discover New Music

Browse new releases and featured playlists:

```bash
# Step 1: Get new releases
# No ID needed - browses new releases
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/new-releases?limit=50&api_token=YOUR_API_TOKEN"

# Step 2: Get featured playlists
# No ID needed - browses featured playlists
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/featured-playlists?limit=20&api_token=YOUR_API_TOKEN"

# Step 3: Browse categories
# No ID needed - lists categories
curl -X GET "https://api.lowcodeapi.com/spotify/v1/browse/categories?api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

For a complete list of all 100+ endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/spotify/definition
- **Official Spotify Documentation**: https://developer.spotify.com/documentation/web-api

## Rate Limits & Best Practices

- **Rate Limit**: Approximately 180 requests per 30 seconds per user
- **Best Practices**:
  - Cache track, artist, and album IDs when working with multiple items
  - Use bulk endpoints for multiple items (albums, tracks, audio features)
  - Implement proper pagination with limit/offset parameters
  - Use market parameter for consistent results across regions
  - Handle 404 responses gracefully for content not available in user's market
  - Store playlist and user IDs to avoid repeated lookups
  - Use Web API for data, Spotify Web Playback SDK for playback control

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Spotify
  }
}
```

Common error responses:
- **400**: Invalid request
- **401**: Invalid or expired token
- **403**: Premium required
- **404**: Resource not found
- **429**: Rate limit exceeded
- **500**: Spotify server error