developers_title

developers_subtitle

developers_overview

The Verbatims API provides programmatic access to our curated collection of quotes, authors, and references. All responses are in JSON format and follow a consistent structure.

Base URL: https://verbatims.cc

developers_authentication

All API requests require an API key sent via the Authorization header. You can manage your keys from your developer dashboard.

# Replace with your actual key

curl https://verbatims.cc/api/v1/me \
-H "Authorization: Bearer vbt_your_api_key_here"

developers_rate_limiting

Rate limits depend on your API key's tier. Response headers include your remaining quota:

X-RateLimit-Remaining: 987

X-RateLimit-Reset: 1696000000

free1,000 requests per hour

pro10,000 requests per hour

enterpriseCustom rate limits

developers_response_format

All responses follow a consistent JSON structure:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "content": "The only way to do great work is to love what you do.",
      "language": "en",
      "stats": {
        "views": 15234,
        "likes": 892,
        "shares": 431
      },
      "featured": true,
      "author": {
        "id": 42,
        "name": "Steve Jobs",
        "fictional": false,
        "image_url": null
      },
      "reference": {
        "id": 7,
        "name": "Stanford Commencement Speech",
        "type": "speech"
      },
      "tags": [
        {
          "name": "inspiration",
          "color": "#3B82F6"
        }
      ],
      "created_at": 1700000000000,
      "updated_at": 1700000000000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

developers_endpoints

GET/api/v1/quotes

List approved quotes with pagination, filtering, and search.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`language`	string	—	Filter by language (e.g. en, fr)
`author_id`	integer	—	Filter by author ID
`reference_id`	integer	—	Filter by reference ID
`tag`	string	—	Filter by tag name
`search`	string	—	Search in quote content
`sort_by`	string	created_at	created_at, updated_at, views_count, likes_count
`sort_order`	string	desc	asc or desc

GET/api/v1/quotes/{id}

Get a single approved quote by ID with full details.

Parameter	Type	Default	Description
`id`*	integer		Quote ID

GET/api/v1/random

Get one or more random quotes.

Parameter	Type	Default	Description
`limit`	integer	1	Number of random quotes (max 10)

GET/api/v1/authors

List authors sorted by popularity.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	—	Search by name

GET/api/v1/authors/{id}

Get a single author by ID.

Parameter	Type	Default	Description
`id`*	integer		Author ID

GET/api/v1/references

List references (sources) sorted by popularity.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`search`	string	—	Search by name
`type`	string	—	Filter by type (film, book, tv_series, ...)

GET/api/v1/references/{id}

Get a single reference by ID.

Parameter	Type	Default	Description
`id`*	integer		Reference ID

GET/api/v1/tags

List tags sorted by quote count.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 100)

GET/api/v1/search

Search across quotes, authors, or references.

Parameter	Type	Default	Description
`q`*	string		Search query (min 2 characters)
`type`	string	quotes	Scope: quotes, authors, or references
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)

GET/api/v1/me

Get information about the current API key.

GET/api/v1/social/queue

List the social queue for a platform with stats and resolved quote content. Requires a moderator or admin key with social:read.

Parameter	Type	Default	Description
`platform`	string	x	x, bluesky, instagram, threads, facebook, pinterest
`status`	string	—	queued, processing, posted, failed, or active
`search`	string	—	Search by quote, author, reference, or source
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)

POST/api/v1/social/queue

Add approved quotes to the social queue for a platform. Requires a moderator or admin key with social:write.

Parameter	Type	Default	Description
`quote_ids`*	array		Approved quote IDs to enqueue (max 200)
`platform`	string	x	x, bluesky, instagram, threads, facebook, pinterest
`scheduled_for`	string	—	Optional future publish time (ISO 8601)

POST/api/v1/social/queue/run-now

Immediately run the social autopost for a platform. Throttled to 1 call per minute. Requires a moderator or admin key with social:write.

Parameter	Type	Default	Description
`platform`	string	—	Target platform, or all enabled platforms if omitted

GET/api/v1/social/platforms

List supported platforms with their enabled status and queue stats. Requires a moderator or admin key with social:read.

developers_example

Fetch the 5 most recent quotes in French:

curl -H "Authorization: Bearer vbt_your_key_here" \
  "https://verbatims.cc/api/v1/quotes?language=fr&limit=5&sort_by=created_at&sort_order=desc" \
  | python3 -m json.tool

developers_api_status

Check the real-time availability of the Verbatims API on our status page.

developers_error_codes

401Missing, invalid, or inactive API key

429Rate limit exceeded. Check X-RateLimit-Reset header

404Resource not found

400Invalid request parameters

500Internal server error