API Documentation

Authentication

All API requests must include your API key in the X-API-Key request header. API keys are issued through your dashboard.

GET /api/v1/check?url=https://example.com/article
X-API-Key: tdr_live_your_api_key_here

API keys follow the format tdr_live_ followed by 32 hexadecimal characters. Keys are shown only once at creation — store yours securely. Do not embed keys in client-side code or public repositories.

Single check

GET /api/v1/check

Check whether a URL or content hash is registered in the Training Data Registry. Supply either url or hash — not both.

Query parameters

Example requests

# Check by URL
GET /api/v1/check?url=https://example.com/my-article
X-API-Key: tdr_live_...

# Check by content hash
GET /api/v1/check?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-API-Key: tdr_live_...

URL normalisation

URLs are normalised before lookup: schemes are lowercased, trailing slashes removed, and fragments stripped. URLs without a scheme are assumed to be HTTPS. You do not need to pre-normalise URLs before sending them.

Bulk check

POST /api/v1/check/bulk

Check multiple URLs in a single request. Available on paid tiers only. Each URL in the batch counts as one query against your monthly allowance.

Tier limits

Request body

POST /api/v1/check/bulk
X-API-Key: tdr_live_...
Content-Type: application/json

{
  "urls": [
    "https://example.com/article-1",
    "https://example.com/article-2",
    "https://blog.example.com/post-3"
  ]
}

Response

{
  "success": true,
  "stats": {
    "total": 3,
    "checked": 3,
    "registered": 1,
    "not_registered": 2,
    "errors": 0,
    "processing_time_ms": 142
  },
  "results": [
    {
      "url": "https://example.com/article-1",
      "registered": true,
      "source": "domain",
      "trust": "verified",
      "domain": "example.com",
      "allow_training": false,
      "allow_inference": false,
      "allow_archive": false,
      "verification_status": "domain-verified",
      "registered_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "url": "https://example.com/article-2",
      "registered": false
    },
    {
      "url": "https://blog.example.com/post-3",
      "registered": false
    }
  ],
  "rate_limit": {
    "limit": 10000,
    "used": 3,
    "remaining": 9997
  },
  "checked_at": "2026-02-26T12:00:00.000Z"
}

If any URLs fail validation, they appear in an errors array alongside the results array. Results maintain the same order as the input array.

Response format

Not registered

{
  "registered": false,
  "checked_at": "2026-02-26T12:00:00.000Z"
}

Registered — URL-level

{
  "registered": true,
  "source": "url",
  "trust": "verified",
  "url": "https://example.com/specific-article",
  "registration_id": "reg_abc123",
  "allow_training": false,
  "allow_inference": true,
  "allow_archive": false,
  "verification_status": "domain-verified",
  "registered_at": "2026-01-15T10:00:00.000Z",
  "checked_at": "2026-02-26T12:00:00.000Z"
}

Registered — domain-level

{
  "registered": true,
  "source": "domain",
  "trust": "verified",
  "domain": "example.com",
  "allow_training": false,
  "allow_inference": false,
  "allow_archive": false,
  "verification_status": "domain-verified",
  "registered_at": "2026-01-10T09:00:00.000Z",
  "checked_at": "2026-02-26T12:00:00.000Z"
}

Response fields

Rate limits

Monthly query limits apply based on your subscription tier. Limits reset at the start of each calendar month (UTC). Current tier allowances are shown on our pricing page.

Rate limit headers

Every response includes the following headers:

When a request is rejected due to quota exhaustion, a 429 response is returned with an additional X-RateLimit-Reset header containing the UTC timestamp when your allowance resets.

Error codes

Error responses follow a consistent format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

Code examples

curl

# Single URL check
curl -s -H "X-API-Key: tdr_live_your_key" \
  "https://trainingdataregistry.org/api/v1/check?url=https://example.com/article"

# Bulk check
curl -s -X POST \
  -H "X-API-Key: tdr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/article-1","https://example.com/article-2"]}' \
  "https://trainingdataregistry.org/api/v1/check/bulk"

JavaScript

const API_KEY = process.env.TDR_API_KEY;
const BASE_URL = 'https://trainingdataregistry.org/api/v1';

// Single check
async function checkUrl(url) {
  const response = await fetch(
    `${BASE_URL}/check?url=${encodeURIComponent(url)}`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.json();
}

// Bulk check
async function checkUrls(urls) {
  const response = await fetch(`${BASE_URL}/check/bulk`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ urls }),
  });
  return response.json();
}

// Example usage
const result = await checkUrl('https://example.com/my-article');
if (result.registered && !result.allow_training) {
  console.log('Content is opted out of AI training');
}

Python

import os
import requests
from urllib.parse import urlencode

API_KEY = os.environ['TDR_API_KEY']
BASE_URL = 'https://trainingdataregistry.org/api/v1'
HEADERS = {'X-API-Key': API_KEY}

def check_url(url: str) -> dict:
    params = urlencode({'url': url})
    response = requests.get(f'{BASE_URL}/check?{params}', headers=HEADERS)
    response.raise_for_status()
    return response.json()

def check_urls(urls: list[str]) -> dict:
    response = requests.post(
        f'{BASE_URL}/check/bulk',
        headers={**HEADERS, 'Content-Type': 'application/json'},
        json={'urls': urls},
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = check_url('https://example.com/my-article')
if result['registered'] and not result.get('allow_training', False):
    print('Content is opted out of AI training')

Best practices