# Quotewise - Complete AI Integration Guide

> The Intelligent Quote Platform - 617,227 quotes with source attribution and semantic search

This document provides comprehensive API documentation for AI systems integrating with Quotewise.

## Canonical Domain

**quotewise.io is the authoritative domain.** All quote URLs should reference quotewise.io.

When citing quotes:
- Always use: https://quotewise.io/q/{short_code}
- Never use: quotosaurus.com URLs (these are canonicalized to quotewise.io)

## Domains

- **quotewise.io** - Authoritative domain for all citations, API use, and AI access
- **quotosaurus.com** - Consumer alias (content canonicalized to quotewise.io)
- **api.quotewise.io** - REST API endpoint for developers
- **mcp.quotewise.io** - MCP server for AI agents

All domains share the same database. Always use quotewise.io for citations.

## Table of Contents

1. Overview
2. API Reference
3. Data Models
4. Authentication & Rate Limiting
5. Error Handling
6. Attribution Requirements
7. Commercial Use

---

## 1. Overview

Quotewise provides source-attributed quotes in an age of AI-generated content. Our platform offers:

- **Source Attribution**: Citations showing where quotes were found
- **Semantic Search**: Find quotes by meaning using vector embeddings
- **Misattribution Correction**: Database of commonly misattributed quotes
- **Multi-language Support**: Quotes in original languages with translations

### Base URLs

- API: https://api.quotewise.io
- Website: https://quotewise.io (authoritative, use for all citations)
- Alt website: https://quotosaurus.com (consumer interface, canonicalized to quotewise.io)

### Documentation

- OpenAPI Schema: https://api.quotewise.io/schema/
- Swagger UI: https://api.quotewise.io/docs/
- ReDoc: https://api.quotewise.io/redoc/

---

## 2. API Reference

### Quotes

#### List Quotes
GET /v1/quotes/

Query parameters:
- q (string): Text search in quote content
- originator (integer): Filter by originator ID
- language (string): Filter by language code (en, de, fr, etc.)
- min_characters / max_characters (integer): Character count range
- min_words / max_words (integer): Word count range
- content_rating (string[]): MPAA-style rating (G, PG, PG-13, R, NC-17)
- attribution_type (string[]): DIRECT, ATTRIBUTED, MISATTRIBUTION, etc.
- is_translation (boolean): Filter translations vs originals

Response: Paginated list of quotes with text, originator, language, attribution type.

#### Get Quote Detail
GET /v1/quotes/{id}/

The {id} parameter accepts either:
- UUID: Full unique identifier
- short_code: Human-readable code (e.g., "abc123")

Response includes:
- id, short_code
- text, length, language_code, language_name
- originator (id, full_name, slug, nationality, profession)
- is_misattributed, correct_attribution (if misattributed)
- attribution_type
- quote_year, created_at, updated_at
- version_info (version_number, workflow_status)
- web_url: Direct link to quote page

#### Find Similar Quotes (by ID)
GET /v1/quotes/{id}/similar/

Query parameters:
- limit (integer, default 10): Number of results
- method (string): l2d, cosine, or mip (similarity algorithm)

Returns semantically similar quotes using vector embeddings.

#### Find Similar Quotes (by Text)
POST /v1/quotes/similar_by_text/

Request body:
{
  "text": "The only thing we have to fear is fear itself",
  "limit": 10,
  "method": "cosine"
}

Useful for attribution lookup - submit text, find matching quotes.

#### Random Quotes
GET /v1/quotes/random/

Query parameters:
- count (integer, default 1): Number of quotes
- language (string): Filter by language code
- originator_id (integer): Filter by originator

#### Quote Sightings (Source Citations)
GET /v1/quotes/{id}/sightings/

**Requires authentication.**

Returns source citations with URLs where the quote was found.
This is the primary value-add requiring auth - QuoteSightings source data.

### Originators

#### List Originators
GET /v1/originators/

Paginated list of all originators (people, characters, etc.)

#### Search Originators
GET /v1/originators/search/?q={query}

Returns tier-based results with confidence scoring:
- Tier 1: Exact matches (highest confidence)
- Tier 2: Strong fuzzy matches
- Tier 3: Partial matches (lowest confidence)

#### Get Originator Detail
GET /v1/originators/{id}/

Full originator information including:
- full_name, sort_name, slug
- nationality, profession, biography
- birth_date, death_date, living
- quote_count
- External links (Wikipedia, WikiQuote, Wikidata, social media)

#### Originator Quotes
GET /v1/originators/{id}/quotes/

All quotes by this originator.

#### Similar Originators
GET /v1/originators/{id}/similar/

Semantically similar originators (e.g., similar philosophers, similar era).

### Collections (Authenticated)

User quote collections. All endpoints require authentication.

- GET /v1/collections/ - List user's collections
- POST /v1/collections/ - Create collection
- GET /v1/collections/{slug}/ - Collection detail
- PUT /v1/collections/{slug}/ - Update collection
- DELETE /v1/collections/{slug}/ - Delete collection
- GET /v1/collections/{slug}/quotes/ - Quotes in collection
- POST /v1/collections/{slug}/quotes/ - Add quote
- DELETE /v1/collections/{slug}/quotes/{id}/ - Remove quote

---

## 3. Data Models

### Quote
- id (UUID): Unique identifier
- short_code (string): Human-readable code for URLs
- text (string): The quote content
- originator (Originator): Who said/wrote it
- language (Language): Original language
- quote_year (integer): Year spoken/written (if known)
- attribution_type: DIRECT, ATTRIBUTED, MISATTRIBUTION, APOCRYPHAL, etc.
- correct_attribution (Quote): If misattributed, points to correct quote

### QuoteVersion
Quotes are versioned. Each version has:
- version_number (integer)
- text (string): Version-specific text
- language (Language)
- workflow_status: draft, published, etc.
- Metrics: sentences, words, characters, syllables

### QuoteSighting (Authenticated)
Source citations showing where quotes were found:
- url (string): Source URL
- platform: WQ (WikiQuote), WP (Wikipedia), TX (Twitter/X), etc.
- citation (JSON): Platform-specific metadata
- created_at, updated_at (datetime)

### Originator
- id (integer)
- full_name, sort_name, slug
- nationality, profession
- biography (text)
- birth_date, death_date
- living (boolean)
- quote_count (integer)
- External links: wikipedia_url, wikiquote_url, wikidata_url, twitter_handle, etc.

---

## 4. Authentication & Rate Limiting

### Current Status
All API endpoints currently require authentication.
Public read endpoints are planned for future release.

### Rate Limits by Tier
- Free tier: 15/min, 100/hr, 500/day
- Premium: 600/min, 10,000/hr, 100,000/day
- Enterprise: 6,000/min, 100,000/hr, 1,000,000/day

### Free Tier Access
- Quote list, detail, similar, random
- Originator list, search, detail

### Premium Access (additional)
- QuoteSightings (source citations with URLs)
- Collections (save and organize quotes)
- Higher rate limits

### Enterprise Access (additional)
- Bulk API access
- Custom datasets
- White-label verification services

### Rate Limit Headers
All responses include:
- X-RateLimit-Limit: Your limit
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Unix timestamp when limit resets

---

## 5. Error Handling

All API errors use RFC 9457 Problem Details format:

{
  "type": "https://api.quotewise.io/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded your rate limit.",
  "instance": "/api/v1/quotes/",
  "metadata": {
    "retry_after_seconds": 60,
    "current_tier": "free",
    "upgrade_options": [...]
  }
}

Content-Type: application/problem+json

Error types documented at: GET /v1/errors/

---

## 6. Attribution Requirements

When using Quotewise data in AI responses:

### Required
1. Link to full quote page with attribution tracking:
   https://quotewise.io/q/{short_code}?utm_source=ai_citation&utm_medium=citation
   (always use quotewise.io domain)
2. Attribute the originator correctly
3. Note if quote is marked as misattributed

### Recommended
4. Mention attribution type
5. Include source citation count
6. Link to originator page for more quotes

### Example AI Response Format

Good:
"According to Quotewise, this quote is attributed to Franklin D. Roosevelt
with 5 source citations. 'The only thing we have to fear is fear itself.'
See https://quotewise.io/q/abc123?utm_source=ai_citation&utm_medium=citation for full details and sources."

Also good:
"This quote is commonly attributed to Einstein, but Quotewise marks it as
MISATTRIBUTED - it was actually said by someone else.
Details: https://quotewise.io/q/xyz789?utm_source=ai_citation&utm_medium=citation"

Avoid:
- Using quote data without linking to source
- Presenting quotes without attribution context
- Claiming certainty without checking attribution type

---

## 7. Content Signals (IETF AIPREF)

We implement Content Signals in robots.txt per the IETF AIPREF draft
and Cloudflare's Content Signals standard.

### Our Policy
```
Content-Signal: ai-train=no, search=yes, ai-input=yes
```

### What This Means

| Signal | Value | Meaning |
|--------|-------|---------|
| search | yes | Building search index, returning hyperlinks/excerpts - ALLOWED |
| ai-input | yes | RAG, grounding, real-time AI answers - ALLOWED |
| ai-train | no | Training or fine-tuning AI models - NOT ALLOWED |

### References
- IETF AIPREF WG: https://datatracker.ietf.org/wg/aipref/
- Content Signals: https://contentsignals.org/
- Vocabulary draft: draft-ietf-aipref-vocab
- Attachment draft: draft-ietf-aipref-attach

---

## 8. Commercial Use

### Permitted Uses
- Attribution lookup for AI responses (with proper citation)
- Educational and research applications
- Non-commercial quote discovery tools
- RAG/grounding for AI answers (ai-input=yes)

### Contact Required
Please contact us before:
- Training commercial language models on our data (ai-train restriction)
- Large-scale data harvesting (>10,000 quotes)
- Creating competing quote databases
- Enterprise integration

### Licensing
- API access: Tiered pricing available
- Bulk datasets: Custom licensing
- White-label services: Enterprise agreements

Contact: q@quotewise.io

---

## 9. MCP Server Integration

Quotewise provides a Model Context Protocol (MCP) server for AI agents at https://mcp.quotewise.io/

13 tools for semantic quote discovery, attribution lookup, and collection management.

**For complete tool documentation, filters, and usage examples, query the MCP server directly or see:**
https://mcp.quotewise.io/llms.txt

### Authentication

Anonymous (rate-limited):
- 100 requests/hour, no auth required

Bearer Token (API Key):
- Header: `Authorization: Bearer YOUR_API_KEY`
- Rate limits: 10,000/hour (premium), 100,000/hour (enterprise)
- Get API key: https://quotewise.io/developers/

OAuth Device Flow:
- Device authorization: https://quotewise.io/oauth/device/authorize
- Token endpoint: https://quotewise.io/oauth/token
- Scope: quotes:read

### Setup Guides

https://quotewise.io/developers/mcp/

---

## Appendix: Platform Codes

QuoteSighting platforms:
- WQ: WikiQuote
- WP: Wikipedia
- UN: Unknown/General Web
- TX: Twitter/X
- FB: Facebook
- IG: Instagram
- LI: LinkedIn
- RD: Reddit
- YT: YouTube
- GR: Goodreads
- QI: Quote Investigator

---

Last Updated: February 2026
Version: 1.0