Developer Documentation

Validity Index API

Programmatic access to the Validly Index. Build tools that demand verification.

Authentication & Security

The Validity Index API requires a unique API key for all requests. Keys are scoped to specific endpoints and are tied to your organization's IP whitelist. We utilize Bearer token authentication via HTTPS.

To maintain the integrity of the archive, all endpoints enforce strict TLS 1.3 encryption. If a request is made without a valid Authorization header, the server will return a 401 Unauthorized status.

Header: Authorization: Bearer <YOUR_API_KEY>

Terminal window displaying encrypted API handshake logs

Core Endpoints

The API is structured around three primary resources: Outlet verification scores, Metadata definitions, and Historical integrity logs.

GET /v1/scores

Verification Scores

Returns the current Validity Score (0.0–1.0) for a specific claim ID or URL. Includes confidence intervals and the timestamp of the last verification audit.

Params: id, url, format=json

GET /v1/outlets

Outlet Metadata

Retrieves the editorial profile and bias vector for a registered media organization. This endpoint provides the systemic context required for accurate score interpretation.

Params: domain, org_id, type=string

GET /v1/history

Integrity Logs

Accesses the immutable change log for any archived asset. Returns a chronological list of edits, retractions, or context additions made to the source material.

Params: asset_id, limit=50, offset=0

Rate Limits

To ensure system stability and equitable access to the archive, the API enforces strict rate limiting based on your subscription tier.

Standard Tier 100 req / minute
Research Tier 1,000 req / minute
Enterprise Tier Custom / Unlimited

Exceeding these limits will result in a 429 Too Many Requests response. The Retry-After header indicates the number of seconds to wait before the next request.

[SYSTEM LOAD METRICS]

Implementation Examples

Python requests

import requests

API_KEY = "vly_live_88291..."
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json"
}

response = requests.get(
    "https://api.validly.org/v1/scores",
    params={"url": "https://news.example.com/article"},
    headers=HEADERS
)

data = response.json()
print(f"Validity Score: {data['score']}")

JavaScript fetch

const apiKey = "vly_live_88291...";
const targetUrl = "https://news.example.com/article";

fetch(`https://api.validly.org/v1/scores?url=${encodeURIComponent(targetUrl)}`, {
    method: "GET",
    headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
    }
})
.then(res => res.json())
.then(data => {
    console.log(`Integrity Score: ${data.score}`);
    console.log(`Confidence: ${data.confidence}`);
});

Initialize Integration

Request a developer key or upgrade your institutional tier to access the full index.

Generate API Key