Api

Playlists

API reference for Playlist endpoints — list, search, and retrieve curated quote collections.

Playlists

The Playlists endpoints allow you to browse, search, and retrieve curated collections of quotes. Playlists can be community-created or officially curated by the Quote Gallery team.

List Playlists

Retrieve a paginated list of public playlists.

GET /api/v1/playlists

Query Parameters

Parameter	Type	Required	Default	Description
`search`	`string`	No	—	Search playlists by name (case-insensitive partial match)
`categories`	`string`	No	—	Comma-separated list of categories to filter by
`limit`	`number`	No	`20`	Number of results per page (max `100`)
`offset`	`number`	No	`0`	Pagination offset

Example Request

curl -H "X-API-Key: your_api_key_here" \
  "https://quotegallery.nl/api/v1/playlists?search=motivational&limit=5"

const response = await fetch(
  'https://quotegallery.nl/api/v1/playlists?search=motivational&limit=5',
  {
    headers: { 'X-API-Key': process.env.QUOTE_GALLERY_API_KEY },
  }
)

const { data, pagination } = await response.json()

import requests
import os

response = requests.get(
    'https://quotegallery.nl/api/v1/playlists',
    headers={'X-API-Key': os.environ['QUOTE_GALLERY_API_KEY']},
    params={
        'search': 'motivational',
        'limit': 5,
    }
)

data = response.json()

Example Response

{
  "data": [
    {
      "id": "playlist123",
      "name": "Motivational Mornings",
      "description": "Start your day with inspiration",
      "iconUrl": "https://...",
      "bannerUrl": "https://...",
      "categories": ["inspirational", "success"],
      "likeCount": 89,
      "quoteCount": 25,
      "creatorName": "quotefan",
      "isCurated": false
    }
  ],
  "pagination": {
    "total": 35,
    "limit": 5,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

Field	Type	Description
`data`	`array`	Array of playlist objects
`data[].id`	`string`	Unique identifier for the playlist
`data[].name`	`string`	Playlist display name
`data[].description`	`string`	Description of the playlist's theme or purpose
`data[].iconUrl`	`string \| null`	URL to the playlist's icon image, or `null` if not set
`data[].bannerUrl`	`string \| null`	URL to the playlist's banner image, or `null` if not set
`data[].categories`	`string[]`	List of category slugs associated with the playlist
`data[].likeCount`	`number`	Number of likes the playlist has received
`data[].quoteCount`	`number`	Number of quotes in the playlist
`data[].creatorName`	`string`	Display name of the user who created the playlist
`data[].isCurated`	`boolean`	Whether the playlist is officially curated by the Quote Gallery team
`pagination.total`	`number`	Total number of matching playlists
`pagination.limit`	`number`	Number of results per page
`pagination.offset`	`number`	Current offset
`pagination.hasMore`	`boolean`	Whether more results are available

Get Playlist by ID

Retrieve a single playlist by its unique identifier. Optionally include the playlist's quotes in the response.

GET /api/v1/playlists/:id

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the playlist

Query Parameters

Parameter	Type	Required	Default	Description
`include_quotes`	`boolean`	No	`false`	When `true`, includes the playlist's quotes in the response
`language`	`string`	No	—	Preferred language for quote texts (only applies when `include_quotes=true`)

Example Request

# Get playlist metadata only
curl -H "X-API-Key: your_api_key_here" \
  "https://quotegallery.nl/api/v1/playlists/playlist123"

# Get playlist with all quotes in English
curl -H "X-API-Key: your_api_key_here" \
  "https://quotegallery.nl/api/v1/playlists/playlist123?include_quotes=true&language=en"

const playlistId = 'playlist123'

// Get playlist with quotes
const response = await fetch(
  `https://quotegallery.nl/api/v1/playlists/${playlistId}?include_quotes=true&language=en`,
  {
    headers: { 'X-API-Key': process.env.QUOTE_GALLERY_API_KEY },
  }
)

const { data: playlist } = await response.json()

console.log(`${playlist.name} — ${playlist.quoteCount} quotes`)
playlist.quotes?.forEach((quote) => {
  console.log(`  "${quote.text}" — ${quote.author.name}`)
})

playlist_id = 'playlist123'

response = requests.get(
    f'https://quotegallery.nl/api/v1/playlists/{playlist_id}',
    headers={'X-API-Key': os.environ['QUOTE_GALLERY_API_KEY']},
    params={
        'include_quotes': 'true',
        'language': 'en',
    }
)

playlist = response.json()['data']

print(f'{playlist["name"]} — {playlist["quoteCount"]} quotes')
for quote in playlist.get('quotes', []):
    print(f'  "{quote["text"]}" — {quote["author"]["name"]}')

Example Response

{
  "data": {
    "id": "playlist123",
    "name": "Motivational Mornings",
    "description": "Start your day with inspiration",
    "iconUrl": "https://...",
    "bannerUrl": "https://...",
    "categories": ["inspirational", "success"],
    "likeCount": 89,
    "quoteCount": 25,
    "creatorName": "quotefan",
    "isCurated": false,
    "quotes": [
      {
        "id": "abc123",
        "text": "The only way to do great work is to love what you do.",
        "language": "en",
        "categories": ["wisdom"],
        "likeCount": 42,
        "author": {
          "id": "xyz789",
          "name": "Steve Jobs"
        }
      }
    ]
  }
}

Response Fields

Field	Type	Description
`data`	`object`	The playlist object
`data.id`	`string`	Unique identifier for the playlist
`data.name`	`string`	Playlist display name
`data.description`	`string`	Description of the playlist
`data.iconUrl`	`string \| null`	URL to the playlist's icon image
`data.bannerUrl`	`string \| null`	URL to the playlist's banner image
`data.categories`	`string[]`	List of category slugs
`data.likeCount`	`number`	Number of likes
`data.quoteCount`	`number`	Number of quotes in the playlist
`data.creatorName`	`string`	Display name of the playlist creator
`data.isCurated`	`boolean`	Whether the playlist is officially curated
`data.quotes`	`array \| undefined`	Playlist's quotes (only present when `include_quotes=true`)
`data.quotes[].id`	`string`	Quote's unique identifier
`data.quotes[].text`	`string`	The quote text
`data.quotes[].language`	`string`	Language code of the quote
`data.quotes[].categories`	`string[]`	Categories the quote belongs to
`data.quotes[].likeCount`	`number`	Number of likes on the quote
`data.quotes[].author`	`object`	The quote's author
`data.quotes[].author.id`	`string`	Author's unique identifier
`data.quotes[].author.name`	`string`	Author's display name

Error Responses

Status	Description
`404`	Playlist not found — the provided ID does not match any public playlist
`401`	Unauthorized — missing or invalid API key

Use Cases

Here are some common patterns for working with the Playlists endpoints:

Curated Playlists Widget

Display only officially curated playlists in a featured section:

async function getCuratedPlaylists(apiKey) {
  const response = await fetch(
    'https://quotegallery.nl/api/v1/playlists?limit=100',
    { headers: { 'X-API-Key': apiKey } }
  )

  const { data } = await response.json()

  // Filter for curated playlists on the client side
  return data.filter((playlist) => playlist.isCurated)
}

Playlist Slideshow

Build a slideshow that cycles through quotes from a specific playlist:

async function getPlaylistSlideshow(apiKey, playlistId) {
  const response = await fetch(
    `https://quotegallery.nl/api/v1/playlists/${playlistId}?include_quotes=true&language=en`,
    { headers: { 'X-API-Key': apiKey } }
  )

  const { data: playlist } = await response.json()

  let currentIndex = 0

  return {
    playlist,
    next() {
      const quote = playlist.quotes[currentIndex]
      currentIndex = (currentIndex + 1) % playlist.quotes.length
      return quote
    },
    get total() {
      return playlist.quotes.length
    },
  }
}

Category-based Playlist Discovery

Help users find playlists related to specific topics:

async function discoverPlaylists(apiKey, category) {
  const response = await fetch(
    `https://quotegallery.nl/api/v1/playlists?categories=${encodeURIComponent(category)}&limit=20`,
    { headers: { 'X-API-Key': apiKey } }
  )

  const { data, pagination } = await response.json()

  return {
    playlists: data,
    total: pagination.total,
  }
}

Export Playlist to Markdown

Download a playlist and format it as a readable Markdown document:

import requests
import os

api_key = os.environ['QUOTE_GALLERY_API_KEY']
playlist_id = 'playlist123'

response = requests.get(
    f'https://quotegallery.nl/api/v1/playlists/{playlist_id}',
    headers={'X-API-Key': api_key},
    params={'include_quotes': 'true', 'language': 'en'}
)

playlist = response.json()['data']

# Build Markdown output
lines = [
    f'# {playlist["name"]}',
    '',
    f'> {playlist["description"]}',
    '',
    f'*{playlist["quoteCount"]} quotes · {playlist["likeCount"]} likes*',
    '',
    '---',
    '',
]

for i, quote in enumerate(playlist.get('quotes', []), 1):
    lines.append(f'{i}. "{quote["text"]}" — **{quote["author"]["name"]}**')
    lines.append('')

print('\n'.join(lines))

Edit this pageorReport an issue

Authors

API reference for Author endpoints — list, search, and retrieve authors with their metadata and quotes.