API Documentation

Everything you need to integrate Airquote into your application.

Quick Start

Make your first API call in seconds. You'll need an API key from your dashboard.

bash

curl -X POST https://airquote.io/api/v1/search \
  -H "Authorization: Bearer aq_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "the meaning of life"}'

Authentication

All API requests require authentication. You can authenticate using either method:

Bearer Token

http

Authorization: Bearer aq_your_api_key

API Key Header

http

X-API-Key: aq_your_api_key

Search

POST /api/v1/search

Semantic search for quotes by meaning.

Request Body

json

{
  "query": "persistence in the face of failure",
  "limit": 5,
  "format": "mla",
  "filters": {
    "author": "Samuel Beckett",
    "category": "motivation"
  }
}

Response

json

{
  "quotes": [
    {
      "id": "qt_abc123",
      "text": "Ever tried. Ever failed. No matter. Try again. Fail again. Fail better.",
      "author": "Samuel Beckett",
      "source": "Worstward Ho",
      "year": 1983,
      "similarity": 0.94,
      "verified": true,
      "verification_level": "primary",
      "citation": "Beckett, Samuel. \"Worstward Ho.\" 1983."
    }
  ],
  "meta": {
    "query": "persistence in the face of failure",
    "total": 1,
    "credits_used": 1,
    "credits_remaining": 19
  }
}

GET /api/v1/search

Query-parameter variant for simple integrations.

bash

curl "https://airquote.io/api/v1/search?q=courage&limit=3&format=apa" \
  -H "Authorization: Bearer aq_your_api_key"

Enhance

POST /api/v1/enhance

Get AI-enhanced contextual quote recommendations powered by Claude. Enhanced requests cost additional credits based on the number of quotes returned and context complexity.

Request Body

json

{
  "query": "a quote about perseverance for a graduation speech",
  "context": "The audience is new college graduates entering the workforce.",
  "count": 3,
  "format": "chicago"
}

Response

json

{
  "quotes": [
    {
      "id": "qt_abc123",
      "text": "Ever tried. Ever failed. No matter. Try again. Fail again. Fail better.",
      "author": "Samuel Beckett",
      "source": "Worstward Ho",
      "verified": true,
      "relevance_note": "Speaks directly to the iterative nature of early-career growth.",
      "citation": "Beckett, Samuel. Worstward Ho. New York: Grove Press, 1983."
    }
  ],
  "meta": {
    "credits_used": 3,
    "credits_remaining": 17,
    "model": "claude-sonnet"
  }
}

Credit Calculation

Base cost: 1 credit. Each additional quote requested adds 1 credit. Using the context field adds 1 credit. For example, requesting 3 quotes with context costs 5 credits (1 base + 3 quotes + 1 context).

Random

GET /api/v1/random

Returns a random verified quote. Optionally filter by category or author.

bash

curl "https://airquote.io/api/v1/random?category=philosophy" \
  -H "Authorization: Bearer aq_your_api_key"

Query Parameters

Parameter	Type	Description
category	string	Filter by category
author	string	Filter by author name
format	string	Citation format (mla, apa, chicago, ap, simple)

Response

json

{
  "quote": {
    "id": "qt_xyz789",
    "text": "The unexamined life is not worth living.",
    "author": "Socrates",
    "source": "Apology (Plato)",
    "verified": true
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 18
  }
}

Quote of the Day

GET /api/v1/quote-of-day

Returns the quote of the day. This endpoint does not require authentication and does not consume credits. The response is cached and rotates daily at midnight UTC.

bash

curl https://airquote.io/api/v1/quote-of-day

Response

json

{
  "quote": {
    "id": "qt_daily001",
    "text": "In the middle of difficulty lies opportunity.",
    "author": "Albert Einstein",
    "source": "Letter to a friend, 1940s",
    "verified": true
  },
  "date": "2026-03-06"
}

Rate Limits

Rate limits vary by plan. When you exceed your rate limit, the API returns a 429 Too Many Requests status code.

Plan	Requests/min	Requests/day
Free	10	2,000
Starter	30	10,000
Pro	100	100,000

Rate Limit Headers

All API responses include the following headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Error Codes

Status	Code	Description
401	invalid_api_key	The API key is missing or invalid.
402	insufficient_credits	Your account has no remaining credits. Upgrade your plan or wait for credits to reset.
429	rate_limited	You have exceeded your rate limit. Wait and retry.
500	server_error	An unexpected error occurred on the server.

Error Response Format

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "You have 0 credits remaining. Please upgrade your plan.",
    "status": 402
  }
}

Citation Formats

Pass the format parameter to any endpoint to receive pre-formatted citations.

Format	Example
mla	Beckett, Samuel. "Worstward Ho." 1983.
apa	Beckett, S. (1983). Worstward Ho.
chicago	Beckett, Samuel. Worstward Ho. New York: Grove Press, 1983.
ap	Samuel Beckett, "Worstward Ho," 1983.
simple	-- Samuel Beckett, Worstward Ho (1983)