API Documentation

Complete guide to integrating QuotesJS into your applications. Get access to thousands of inspirational quotes with powerful search and filtering capabilities.

Quick Start

1. Try it without a key

Every endpoint below works with no authentication at all, drawing on an allowance of 5,000 quotes a day per IP address. A free API key raises that to 50,000 and keeps it separate from whatever your browsing uses.

🔑 No key needed to start. When you want your own allowance,create a free account. The /admin endpoints are the only ones that require privileges.

2. Make Your First Request

javascript
// No key: works as-is
fetch('https://quotes.owla.dev/api/quotes?per_page=5')
  .then(response => response.json())
  .then(({ data, pagination }) => console.log(data, pagination.total));

// With a key, which charges your own allowance instead of your IP's
fetch('https://quotes.owla.dev/api/quotes?per_page=5', {
  headers: {
    'x-api-key': 'your-api-key-here'
  }
})
.then(response => response.json())
.then(({ data }) => console.log(data));

// Using curl
curl "https://quotes.owla.dev/api/quotes?per_page=5"

Base URL

https://quotes.owla.dev

Authentication

Header: x-api-key: your-api-key
Query: ?api_key=your-api-key

API Endpoints

Public Endpoints

Check API health and database connectivity.

Get general API information, available endpoints, and rate limits.

Quote Endpoints

Retrieve quotes with optional filtering and search parameters.

Reports both allowances. Works without a key, in which case only the browse meter is filled in. Reading it costs no quota of its own.

Rate Limits

No Account

  • • 5,000 quotes per day, per IP address
  • • All public endpoints
  • • Full search and pagination
  • • This is what browsing the site uses

Free Account

  • • 50,000 quotes per day, per API key
  • • Separate from the browse allowance
  • • Usage statistics

Premium Account

  • • Unlimited quotes
  • • Everything above, without a daily ceiling

How the allowance is counted

Quota counts quotes returned, not requests made, so per_page=100 costs 100 and per_page=1 costs 1. Every response carries the running total, and a 429 tells you when to come back:

javascript
// On every /api/quotes response
"usage": { "meter": "browse", "quotes_today": 40, "daily_limit": 5000, "remaining": 4960 }

// On a 429, alongside a Retry-After header giving seconds until the daily reset
{
  "error": "Daily browse quota exceeded",
  "meter": "browse",
  "quotes_today": 5000,
  "daily_limit": 5000,
  "retryAfterSeconds": 25322
}

// Short-window burst limits also apply and use standard RateLimit headers.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

CodeStatusDescription
200OKRequest successful
400Bad RequestInvalid parameters
401UnauthorizedInvalid or missing API key
429Rate LimitedRate limit exceeded
500Server ErrorInternal server error

Error Response Format

javascript
{
  "error": "Invalid API key",
  "code": 401,
  "message": "Please provide a valid API key in the x-api-key header"
}

Code Examples

JavaScript/Node.js

javascript
// Using async/await
const getQuotes = async () => {
  try {
    const response = await fetch('https://quotes.owla.dev/api/quotes', {
      headers: {
        'x-api-key': 'your-api-key-here'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const quotes = await response.json();
    return quotes;
  } catch (error) {
    console.error('Error fetching quotes:', error);
  }
};

Python

python
import requests

def get_quotes(api_key, **params):
    headers = {'x-api-key': api_key}
    
    try:
        response = requests.get(
            'https://quotes.owla.dev/api/quotes',
            headers=headers,
            params=params
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

# Usage
quotes = get_quotes('your-api-key', limit=5, random=True)

Need Help?

Get started with your free API key and join thousands of developers building amazing applications with quotes.

Get Free API KeyView Dashboard