Introduction

Welcome to the Trustority API documentation. Our API helps you detect scam websites and protect your users by analyzing URLs and returning detailed trust scores.

What You Can Do

• Check if any website is trustworthy or a potential scam
• Get detailed analysis including domain age, SSL status, and content patterns
• Receive a trust score from 0 (dangerous) to 100 (trustworthy)
• Report scam websites to help protect others

Quick Start

Get started in 3 simple steps:

Step 1: Get Your API Key

Sign up at trustority.dev/register to get your free API key.

Step 2: Make Your First Request

curl -X POST https://trustority.dev/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"url": "https://example.com"}'

Step 3: Get the Response

{
  "score": 85,
  "risk_level": "safe",
  "risk_label": "Trustworthy",
  "summary": "example.com appears to be a legitimate website."
}

Authentication

All API requests require authentication using your API key. Include it in the request header:

X-API-Key: ts_your_api_key_here

Without Authentication

You can make limited requests without an API key (10/day from your IP), but we recommend registering for reliable access.

Check URL

Analyze any URL and get a comprehensive trust score.

curl -X POST https://trustority.dev/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ts_your_api_key" \
  -d '{"url": "https://amazon.com"}'

{
  "url": "https://amazon.com",
  "domain": "amazon.com",
  "score": 90,
  "risk_level": "safe",
  "risk_label": "Trustworthy",
  "summary": "amazon.com appears to be a legitimate and trustworthy website.",
  "checks": {
    "domain": {
      "domain_age_days": 11403,
      "creation_date": "1994-11-01",
      "whois_private": false
    },
    "ssl": {
      "has_ssl": true,
      "ssl_valid": true,
      "issuer": "Amazon"
    },
    "dns": {
      "has_mx_records": true,
      "has_a_record": true
    },
    "content": {
      "accessible": true,
      "has_contact_info": true,
      "suspicious_patterns": []
    },
    "blacklist": {
      "on_blacklist": false,
      "is_trusted": true
    }
  },
  "deductions": [
    {
      "check": "no_contact",
      "points": 10,
      "reason": "No contact information found"
    }
  ],
  "cached": false,
  "response_time_ms": 523,
  "checked_at": "2026-01-20T10:30:00Z"
}

Check Domain

Simplified endpoint - just pass the domain in the URL path.

curl https://trustority.dev/api/v1/check/google.com \
  -H "X-API-Key: ts_your_api_key"

Get Usage

Check your current API usage and limits.

curl https://trustority.dev/api/v1/usage \
  -H "X-API-Key: ts_your_api_key"

{
  "tier": "pro",
  "daily_limit": 1000,
  "used_today": 145,
  "remaining": 855,
  "resets_at": "2026-01-21T00:00:00Z"
}

Report Scam

Report a website as a scam to help protect the community.

curl -X POST https://trustority.dev/api/v1/report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ts_your_api_key" \
  -d '{"url": "https://fake-bank-login.com", "reason": "Phishing site impersonating a bank"}'

Trust Score

Every URL check returns a trust score from 0 to 100:

Risk Levels

The risk_level field provides a simple classification:

• safe - Website is trustworthy
• caution - Proceed with some care
• suspicious - Be careful, investigate more
• high_risk - Likely a scam
• dangerous - Avoid this website

Checks Explained

We analyze multiple factors to determine trust:

Domain Analysis

SSL Certificate

DNS Records

Content Analysis

Deductions

The deductions array shows exactly why points were subtracted:

Registration

Create a free account to get your API key:

1. Go to trustority.dev/register
2. Enter your email and password
3. Your API key will be shown on the dashboard

API Keys

Your API key is shown in your dashboard.

API Key Format

ts_2ed120a3b938fabe07e3510fcd628ae932171405edb8960b

All API keys start with ts_ followed by a unique token.

Regenerating Keys

If your key is compromised, regenerate it from the dashboard. The old key will immediately stop working.

Rate Limits

Rate limits are applied daily and reset at midnight UTC.

Rate Limit Headers

Check these response headers to monitor usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 855
X-RateLimit-Reset: 2026-01-21T00:00:00Z

Exceeding Limits

If you exceed your limit, you'll receive a 429 error:

{
  "error": "Rate limit exceeded. Used 1000/1000 requests today."
}

Pricing

Upgrade anytime from your billing page.

Code Examples

Python

import requests

API_KEY = "ts_your_api_key"
URL = "https://trustority.dev/api/v1/check"

response = requests.post(
    URL,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY
    },
    json={"url": "https://example.com"}
)

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

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = 'ts_your_api_key';

axios.post('https://trustority.dev/api/v1/check', {
    url: 'https://example.com'
}, {
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
})
.then(response => {
    console.log('Score:', response.data.score);
    console.log('Risk:', response.data.risk_label);
});

JavaScript (Browser Fetch)

const checkUrl = async (url) => {
    const response = await fetch('https://trustority.dev/api/v1/check', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'ts_your_api_key'
        },
        body: JSON.stringify({ url })
    });
    return response.json();
};

checkUrl('https://example.com').then(console.log);

PHP

<?php
$apiKey = 'ts_your_api_key';
$url = 'https://example.com';

$ch = curl_init('https://trustority.dev/api/v1/check');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['url' => $url]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Score: " . $data['score'];
?>

Ruby

require 'net/http'
require 'json'

uri = URI('https://trustority.dev/api/v1/check')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'ts_your_api_key'
request.body = { url: 'https://example.com' }.to_json

response = http.request(request)
data = JSON.parse(response.body)

puts "Score: #{data['score']}"

Error Handling

The API uses standard HTTP status codes:

Error Response Format

{
  "error": "Rate limit exceeded",
  "detail": "Used 100/100 requests today. Upgrade for more."
}

Best Practices

Caching

Results are cached for 24 hours. The cached: true field indicates a cached result. You don't need to implement your own caching.

Error Handling

Always check for errors and handle rate limits gracefully:

if response.status_code == 429:
    # Wait and retry, or show user-friendly message
    time.sleep(60)
elif response.status_code == 200:
    data = response.json()
    # Process result

Security

• Never expose your API key in client-side code
• Use environment variables to store keys
• Make API calls from your backend server

Frequently Asked Questions

How accurate is the trust score?

Our scoring system analyzes 10+ factors including domain age, SSL, DNS, and content patterns. While no system is 100% accurate, our scores provide reliable guidance. Use the detailed breakdown to make informed decisions.

Can I check any website?

Yes, you can check any publicly accessible URL. Results may be limited for sites that block automated access.

How long are results cached?

Results are cached for 24 hours. After that, a fresh analysis is performed.

What if I need more requests?

Upgrade your plan from the billing page. For enterprise needs, contact us.

Is there a bulk API?

For bulk checks (50+ URLs), contact us for a custom solution.

Contact & Support

Trustority API Documentation v1.0 | trustority.dev