Skip to content

Latest commit

 

History

History
471 lines (362 loc) · 9.53 KB

API_DOCUMENTATION.md

File metadata and controls

471 lines (362 loc) · 9.53 KB

Wikipedia API Documentation

Overview

The Wikipedia API provides fast, intelligent search across 4+ million Wikipedia articles with support for keyword search, semantic search, and tiered access control.

Base URL: https://wiki.built-simple.ai

Features:

  • ⚡ Lightning-fast keyword search (10-15ms average)
  • 🧠 Semantic search capability (vector-based)
  • 🔐 API key authentication + OAuth support
  • 💳 Stripe-powered billing (Free & Pro tiers)
  • 📊 Rate limiting & usage tracking
  • 🚀 4 million+ Wikipedia articles indexed

Authentication

API Keys

All search endpoints require an API key passed via the X-API-Key header.

Get a Free API Key:

curl -X POST https://wiki.built-simple.ai/api/billing/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com"}'

Response:

{
  "api_key": "wp_...",
  "tier": "free",
  "monthly_limit": 100,
  "rate_limit_per_minute": 60,
  "message": "API key created. Upgrade to Pro for 10,000 requests/month."
}

OAuth (Google)

Login:

GET /auth/google/login

Callback:

GET /auth/google/callback?code=...&state=...

Logout:

GET /auth/logout

Pricing Tiers

Feature Free Pro
Price $0/month $29/month
Monthly Requests 100 10,000
Rate Limit 60 req/min 200 req/min
Support Community Priority

Endpoints

1. Keyword Search (Default)

Fast full-text search using SQLite FTS5.

Endpoint: GET /api/search

Parameters:

  • q (required): Search query (max 200 characters)
  • limit (optional): Number of results (1-20, default: 10)

Headers:

  • X-API-Key: Your API key

Example Request:

curl "https://wiki.built-simple.ai/api/search?q=quantum+physics&limit=5" \
  -H "X-API-Key: wp_your_api_key"

Example Response:

{
  "query": "quantum physics",
  "count": 5,
  "results": [
    {
      "id": 12345,
      "title": "Quantum mechanics",
      "summary": "Quantum mechanics is a fundamental theory...",
      "relevance_score": 0.95
    }
  ],
  "time_seconds": 0.012,
  "cached": true,
  "tier": "free"
}

2. Semantic Search

Intelligent semantic/vector-based search using embeddings.

Endpoint: GET /api/search/semantic

Parameters:

  • q (required): Search query
  • limit (optional): Number of results (1-20, default: 10)

Headers:

  • X-API-Key: Your API key

Example Request:

curl "https://wiki.built-simple.ai/api/search/semantic?q=theory+of+relativity" \
  -H "X-API-Key: wp_your_api_key"

Example Response:

{
  "query": "theory of relativity",
  "count": 10,
  "results": [...],
  "time_seconds": 0.045,
  "search_mode": "semantic",
  "vector_search_available": true,
  "tier": "free"
}

Note: Currently returns keyword results as fallback. Full semantic search requires embedding model configuration.

3. Billing Status

Check your API key usage and limits.

Endpoint: GET /api/billing/status

Headers:

  • X-API-Key: Your API key

Example Request:

curl "https://wiki.built-simple.ai/api/billing/status" \
  -H "X-API-Key: wp_your_api_key"

Example Response:

{
  "tier": "free",
  "monthly_requests": 42,
  "monthly_limit": 100,
  "reset_date": "2026-01-01T00:00:00",
  "rate_limit_per_minute": 60
}

4. Pricing Information

Get current pricing tiers and features.

Endpoint: GET /api/pricing

Example Request:

curl "https://wiki.built-simple.ai/api/pricing"

Example Response:

{
  "tiers": {
    "free": {
      "price": 0,
      "requests_per_month": 100,
      "requests_per_minute": 60,
      "features": ["Basic search", "Community support"]
    },
    "pro": {
      "price": 29,
      "currency": "USD",
      "interval": "month",
      "requests_per_month": 10000,
      "requests_per_minute": 200,
      "features": ["10,000 requests/month", "200 requests/minute", "Priority support"]
    }
  }
}

5. API Statistics

Get API capabilities and configuration status.

Endpoint: GET /api/stats

Example Request:

curl "https://wiki.built-simple.ai/api/stats"

Example Response:

{
  "total_articles": "4+ million Wikipedia articles",
  "search_modes": {
    "keyword": "Fast keyword/FTS search (default)",
    "exact": "Exact title matching",
    "phrase": "Phrase search",
    "semantic": "Semantic search (requires configuration)"
  },
  "vector_search": {
    "available": false,
    "total_vectors": 4003880,
    "dimension": 2560,
    "index_type": "FAISS HNSW",
    "status": "Requires embedding model integration"
  },
  "authentication": {
    "api_keys": true,
    "oauth": "Not configured",
    "stripe_billing": "Enabled"
  }
}

6. Health Check

Check API health and uptime.

Endpoint: GET /health

Example Response:

{
  "status": "lightning",
  "timestamp": 1765052174.731537
}

Error Responses

Rate Limit Exceeded

{
  "detail": "Rate limit exceeded. Try again in 30 seconds.",
  "retry_after": 30
}

Status Code: 429

Monthly Limit Exceeded

{
  "detail": "Monthly limit exceeded (100 requests). Upgrade to Pro for more."
}

Status Code: 429

Invalid API Key

{
  "detail": "Invalid API key"
}

Status Code: 401

Invalid Query

{
  "detail": "Query too short (minimum 2 characters)"
}

Status Code: 400

Rate Limits

Tier Requests/Minute Monthly Limit
Free 60 100
Pro 200 10,000

Headers:

  • X-RateLimit-Limit: Your rate limit
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when rate limit resets

Code Examples

Python

import requests

API_KEY = "wp_your_api_key"
BASE_URL = "https://wiki.built-simple.ai"

headers = {"X-API-Key": API_KEY}

# Search
response = requests.get(
    f"{BASE_URL}/api/search",
    params={"q": "artificial intelligence", "limit": 10},
    headers=headers
)
results = response.json()
print(f"Found {results['count']} results in {results['time_seconds']}s")

# Check usage
status = requests.get(f"{BASE_URL}/api/billing/status", headers=headers).json()
print(f"Usage: {status['monthly_requests']}/{status['monthly_limit']}")

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'wp_your_api_key';
const BASE_URL = 'https://wiki.built-simple.ai';

const headers = { 'X-API-Key': API_KEY };

// Search
async function search(query) {
  const response = await axios.get(`${BASE_URL}/api/search`, {
    params: { q: query, limit: 10 },
    headers: headers
  });
  console.log(`Found ${response.data.count} results`);
  return response.data.results;
}

// Check usage
async function checkUsage() {
  const response = await axios.get(`${BASE_URL}/api/billing/status`, { headers });
  console.log(`Usage: ${response.data.monthly_requests}/${response.data.monthly_limit}`);
}

search('quantum mechanics');
checkUsage();

cURL

# Search
curl "https://wiki.built-simple.ai/api/search?q=python+programming" \
  -H "X-API-Key: wp_your_api_key"

# Billing status
curl "https://wiki.built-simple.ai/api/billing/status" \
  -H "X-API-Key: wp_your_api_key"

# Register for free API key
curl -X POST "https://wiki.built-simple.ai/api/billing/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com"}'

Upgrading to Pro

To upgrade to the Pro tier ($29/month):

  1. Via Stripe Checkout:

    curl -X POST "https://wiki.built-simple.ai/api/billing/checkout" \
  -H "X-API-Key: wp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"success_url":"https://yoursite.com/success","cancel_url":"https://yoursite.com/cancel"}'

  2. Follow the Stripe checkout URL returned in the response

  3. Webhook automatically upgrades your account when payment succeeds

Technical Details

Architecture

  • Framework: FastAPI + Uvicorn (async)
  • Database: SQLite with FTS5 full-text search
  • Vector Store: FAISS HNSW (4M vectors, 2560 dimensions)
  • Connection Pooling: 5 pre-warmed connections with WAL mode
  • Caching: LRU cache for frequent queries
  • Performance: 10-15ms average response time

Infrastructure

  • Primary API: CT 102 (192.168.1.181)
  • Vector Search: CT 106 (192.168.1.70:8080)
  • HTTPS: Cloudflare Tunnel
  • Domain: wiki.built-simple.ai

Reliability

  • Uptime Monitoring: Automated health checks every 5 minutes
  • Email Alerts: Downtime notifications
  • Backup Sync: Every 2 hours to offsite storage

Support

Free Tier:

Pro Tier:

  • Priority email support (24-hour response)
  • Direct Slack channel access
  • Custom integration assistance

Changelog

Version 1.2.0 (December 2025)

  • ✅ Added Google OAuth authentication
  • ✅ Added semantic search endpoint
  • ✅ Reduced free tier to 100 requests/month
  • ✅ Added API stats endpoint
  • ✅ Improved documentation

Version 1.1.0 (December 2025)

  • ✅ Migrated from Flask to FastAPI
  • ✅ Added connection pooling (78% performance improvement)
  • ✅ Integrated Stripe billing
  • ✅ Added rate limiting per tier

Version 1.0.0 (October 2025)

  • ✅ Initial release
  • ✅ Keyword search over 4M articles
  • ✅ Basic API key authentication

License

This API is proprietary. Contact us for licensing inquiries.

© 2025 Built Simple. All rights reserved.