Quote API Documentation

Public API Endpoints

The Quote API provides access to our collection of inspiring quotes. All endpoints support CORS and can be accessed from any domain.

Base URL

https://quotegallery.nl/api/v1

Authentication

Anonymous Access

No authentication required
Rate limit: 60 requests/hour
Maximum 10 quotes per request

Authenticated Users

Login via Supabase PKCE auth
Rate limit: 100 requests/hour
Maximum 50 quotes per request

API Key (Recommended for Apps)

Higher rate limits
More reliable service
Contact us for an API key

Usage:

curl -H "x-api-key: YOUR_API_KEY" https://quotegallery.nl/api/v1/quotes/random

Tiers:

Free: 100 requests/hour
Pro: 1,000 requests/hour
Enterprise: Custom limits

Endpoints

Get Random Quote

Get a single random quote from the collection.

GET /api/v1/quotes/random

Query Parameters:

Parameter	Type	Default	Description
`language`	string	`en`	Language code (`en`, `nl`, `tr`)
`category`	string	-	Filter by category (historical, philosophical, etc.)
`author_id`	string	-	Filter by specific author ID
`includeTranslations`	boolean	`false`	Include all translations

Example Request:

curl "https://quotegallery.nl/api/v1/quotes/random?language=en&category=philosophical"

Example Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "author_id": "author-uuid",
  "status": "approved",
  "visibility": "public",
  "categories": ["philosophical"],
  "likes_count": 42,
  "user_liked": false,
  "created_at": "2024-01-15T10:30:00Z",
  "authors": {
    "id": "author-uuid",
    "name": "Albert Einstein",
    "description": "Theoretical physicist",
    "categories": ["scientific", "philosophical"]
  },
  "translation": {
    "text": "Imagination is more important than knowledge.",
    "language": "en"
  }
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 2024-12-13T15:00:00.000Z
X-API-Tier: anonymous

Get Multiple Quotes

Get a paginated list of quotes.

GET /api/v1/quotes

Query Parameters:

Parameter	Type	Default	Description
`page`	number	`1`	Page number
`limit`	number	`10`	Results per page (max: 10 anonymous, 50 authenticated)
`language`	string	`en`	Language code
`category`	string	-	Filter by category
`author_id`	string	-	Filter by author
`sort`	string	`newest`	Sort order (`newest`, `oldest`, `popular`)
`exclude_ids`	string	-	Comma-separated quote IDs to exclude

Example Request:

curl "https://quotegallery.nl/api/v1/quotes?page=1&limit=5&category=philosophical&sort=popular"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "quote-1",
      "translation": {
        "text": "Quote text here...",
        "language": "en"
      },
      "authors": {
        "name": "Author Name"
      },
      "likes_count": 100
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 1247,
    "totalPages": 250
  }
}

Rate Limiting

All API endpoints implement rate limiting to ensure fair usage.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60        # Maximum requests allowed
X-RateLimit-Remaining: 45    # Requests remaining in window
X-RateLimit-Reset: 2024...   # When the limit resets
X-API-Tier: anonymous        # Your access tier

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "statusCode": 429,
  "statusMessage": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait 1800 seconds."
}

Error Responses

All errors follow this format:

{
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "No quotes found matching the criteria"
}

Common Error Codes:

400 - Bad Request (invalid parameters)
404 - Not Found (no quotes match criteria)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Best Practices

Cache responses - Quote data doesn't change frequently
Use API keys - Get higher limits and better reliability
Handle rate limits - Check headers and implement exponential backoff
Filter wisely - Use category/author filters to reduce API calls
Include translations - Set includeTranslations=true if you need multiple languages

Examples

JavaScript/Fetch

const response = await fetch('https://quotegallery.nl/api/v1/quotes/random?language=en', {
  headers: {
    'x-api-key': 'your-api-key-here'
  }
})
const quote = await response.json()
console.log(quote.translation.text)

Python/Requests

import requests

response = requests.get(
    'https://quotegallery.nl/api/v1/quotes/random',
    params={'language': 'en', 'category': 'philosophical'},
    headers={'x-api-key': 'your-api-key-here'}
)
quote = response.json()
print(quote['translation']['text'])

cURL

curl -H "x-api-key: your-key" \
  "https://quotegallery.nl/api/v1/quotes/random?language=en&category=philosophical"

Getting an API Key

Want an API key for your project?

Contact us at: your-email@quotegallery.nl
Describe your use case
Choose a tier (Free/Pro/Enterprise)
Receive your API key within 24 hours

Support

Documentation: https://quotegallery.nl/docs
Issues: https://github.com/your-repo/issues
Email: support@quotegallery.nl

Version: 1.0.0
Last Updated: December 13, 2024

Edit this pageorReport an issue

Examples

Code examples for common use cases