Documentation

API Reference.

Integrate Revealer.US intelligence into your applications via REST API.

Quick Start

01

Get API Key

Generate from Dashboard → Settings

02

Make Request

Send authenticated REST requests

03

Get Results

Receive structured JSON responses

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Security: Never expose your API key in client-side code. Make API calls from your backend.

Example

import requests

API_KEY = "sk_live_..."
BASE_URL = "https://revealer.us"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Verify your API key first
def verify_api_key():
    response = requests.get(f"{BASE_URL}/api/v1/verify", headers=headers)
    return response.json()

# Resolve a username/handle
def resolve_handle(handle):
    response = requests.post(
        f"{BASE_URL}/api/resolve",
        headers=headers,
        json={"handle": handle}
    )
    return response.json()

# Search breach databases
def search_breaches(search_type, term):
    response = requests.post(
        f"{BASE_URL}/api/database/search",
        headers=headers,
        json={"type": search_type, "term": term}
    )
    return response.json()

# Search stealer logs (Elite+)
def search_stealer_logs(search_type, term, limit=35):
    response = requests.post(
        f"{BASE_URL}/api/stealer-logs/search",
        headers=headers,
        json={"type": search_type, "term": term, "limit": limit}
    )
    return response.json()

# Get search history
def get_history(page=1, limit=25):
    response = requests.get(
        f"{BASE_URL}/api/history?page={page}&limit={limit}",
        headers=headers
    )
    return response.json()

# Example usage
result = search_breaches("email", "[email protected]")
if result.get("success"):
    print(f"Found {result['data']['found']} records")

Endpoints

GET/api/v1/infoPublic

Get API information, available endpoints, and your detected IP address (no auth required)

GET/api/v1/verifyPremium+

Verify API key is working and check your access level

POST/api/resolvePremium+

Resolve a handle/username to associated profiles, breach data, and device exposures

POST/api/database/searchPremium+

Search breach databases for exposed credentials and personal data

POST/api/stealer-logs/searchElite+

Search device exposures for compromised credentials (full results require Elite+)

POST/api/stealer-logs/file/[id]/[type]Elite+

Browse detailed contents of a stealer log file

POST/api/discord/lookupPremium+

Lookup Discord user profiles by user ID

GET/api/historyPremium+

Retrieve your search history with pagination

POST/api/historyPremium+

Get cached result for a specific search by ID

GET/api/saved-incidentsPremium+

List all saved credentials/incidents

POST/api/saved-incidentsPremium+

Save a credential/incident to your account

DELETE/api/saved-incidents/[id]Premium+

Delete a saved incident by ID

GET/api/auth/mePremium+

Get current account information, tier, quota, and verify API key

Rate Limits & Quotas

PlanAPIBreach LookupsSocial LookupsDevice ExposuresRateIPs
Free1/day1/day
StarterUnlimited25/day
BasicUnlimited150/day
ProUnlimited500/dayPreviews1/s3
EliteUnlimitedUnlimited100/day3/s5
Unlimited

IP Whitelisting: Configure allowed IPs in Dashboard → Settings → API Access before using the API.

Error Responses

CodeStatusDescription
400Bad RequestInvalid request body or missing required parameters
401UnauthorizedMissing or invalid API key
403ForbiddenIP not whitelisted or insufficient tier access
404Not FoundResource not found
409ConflictResource already exists (e.g., duplicate saved incident)
429Too Many RequestsRate limit or quota exceeded
500Internal Server ErrorServer error - contact support if persistent

Error Response Format:

{
  "success": false,
  "error": "Error message",
  "message": "Human-readable description"
}

Response Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per second
X-RateLimit-Remaining: Remaining requests in window
X-RateLimit-Reset: Unix timestamp when limit resets
X-API-Authenticated: "true" when authenticated
X-Client-IP: Your detected IP address

Troubleshooting

403 Forbidden or Cloudflare Challenge

If you receive 403 errors or see Cloudflare challenge pages:

  1. 1.Check your IP via GET /api/v1/info
  2. 2.Whitelist IP in Dashboard → Settings → API Access
  3. 3.Verify key via GET /api/v1/verify
  4. 4.Confirm subscription is active and tier is Premium+

IP Mismatch

Your server's outgoing IP may differ from local, especially with:

  • Cloud providers (AWS, GCP, Azure) — use instance public IP
  • VPNs/proxies — whitelist exit node IP
  • NAT gateways — whitelist NAT public IP

Required Headers

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
Get Started

Ready to integrate?

Create an account and get your API key.