API DOCUMENTATION

Integrate multi-perspective news analysis into your applications.

The Refract API provides programmatic access to our comparative media analysis data. Use it to build dashboards, research tools, or media monitoring applications.

ENDPOINTS

GET/api/subjects

List subjects

Returns a paginated list of analyzed subjects with metadata, country coverage, and divergence scores.

GET/api/subjects/{slug}

Get subject detail

Returns a single subject with full perspectives, metadata, and tags.

GET/api/subjects/{slug}/comparison

Get comparison data

Returns full comparison data including divergence scores, blind spots, and meta-analysis for a subject.

GET/api/embed/{slug}

Embed widget

Returns a self-contained HTML widget for embedding subject summaries on external sites.

AUTHENTICATION

API access requires authentication via API key. Include your key in the Authorization header.

Authorization: Bearer api_your_key_here

Get your API key from your account settings, or contact us for enterprise access.

RATE LIMITS

FREE

Free tier: 100 requests/day

PREMIUM

Premium tier: 1,000 requests/day

ENTERPRISE

Enterprise: Custom limits

When rate limit is exceeded, the API returns HTTP 429 with reset time.

CODE EXAMPLES

cURL

curl -H "Authorization: Bearer api_your_key_here" \
  -H "Accept: application/json" \
  https://api.therefract.com/api/subjects

Python

import requests

API_KEY = "api_your_key_here"
BASE_URL = "https://therefract.com/api"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json"
}

# List subjects
response = requests.get(f"{BASE_URL}/subjects", headers=headers)
subjects = response.json()["hydra:member"]

for subject in subjects:
    print(f"{subject['title']} - Divergence: {subject.get('aiDivergenceScore', 'N/A')}%")

# Get comparison data
slug = subjects[0]["slug"]
comparison = requests.get(
    f"{BASE_URL}/subjects/{slug}/comparison",
    headers=headers
).json()

print(f"Divergence score: {comparison['divergenceScore']}%")
print(f"Perspectives: {len(comparison['perspectives'])}")

JavaScript

const API_KEY = "api_your_key_here";
const BASE_URL = "https://therefract.com/api";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Accept": "application/json"
};

// List subjects
const response = await fetch(`${BASE_URL}/subjects`, { headers });
const data = await response.json();
const subjects = data["hydra:member"];

// Get comparison data for first subject
const slug = subjects[0].slug;
const comparison = await fetch(
  `${BASE_URL}/subjects/${slug}/comparison`,
  { headers }
).then(r => r.json());

console.log(`Divergence: ${comparison.divergenceScore}%`);
console.log(`Countries: ${comparison.perspectives.length}`);

RESPONSE FORMAT

All responses are in JSON format. Collection endpoints use Hydra pagination format.

GET /api/subjects

{
  "hydra:member": [
    {
      "id": 1,
      "slug": "us-china-trade-tensions",
      "title": "US-China Trade Tensions Escalate",
      "summary": "...",
      "publishedAt": "2026-03-18T10:00:00+00:00",
      "perspectiveCount": 12,
      "aiDivergenceScore": 78,
      "countries": [
        { "code": "us", "name": "United States", "flag": "..." },
        { "code": "cn", "name": "China", "flag": "..." }
      ]
    }
  ],
  "hydra:totalItems": 150
}

INTERACTIVE DOCUMENTATION

Explore the full API specification with Swagger UI.

Open Swagger UI →

GET YOUR API KEY

Ready to integrate The Refract into your workflow? Generate an API key from your account or contact us for enterprise access.

MY ACCOUNT CONTACT US

import requests API_KEY = "api_your_key_here" BASE_URL = "https://therefract.com/api" headers = { "Authorization": f"Bearer {API_KEY}", "Accept": "application/json" } # List subjects response = requests.get(f"{BASE_URL}/subjects", headers=headers) subjects = response.json()["hydra:member"] for subject in subjects: print(f"{subject['title']} - Divergence: {subject.get('aiDivergenceScore', 'N/A')}%") # Get comparison data slug = subjects[0]["slug"] comparison = requests.get( f"{BASE_URL}/subjects/{slug}/comparison", headers=headers ).json() print(f"Divergence score: {comparison['divergenceScore']}%") print(f"Perspectives: {len(comparison['perspectives'])}")

{ "hydra:member": [ { "id": 1, "slug": "us-china-trade-tensions", "title": "US-China Trade Tensions Escalate", "summary": "...", "publishedAt": "2026-03-18T10:00:00+00:00", "perspectiveCount": 12, "aiDivergenceScore": 78, "countries": [ { "code": "us", "name": "United States", "flag": "..." }, { "code": "cn", "name": "China", "flag": "..." } ] } ], "hydra:totalItems": 150 }