Documentation

Authentication

Every request to check and account endpoints requires an API key via bearer token.

Authorization: Bearer uph_your_key_here

API keys are issued on signup and shown once. Store them securely. If you lose yours, rotate it via /v1/keys/rotate.

Quick Start

Choose your path: terminal (CLI), AI tool (MCP), or direct API calls.

unphurl signup --email you@example.com --name "Sarah"

# With a company name
unphurl signup --email you@example.com --name "Sarah" --company "Acme Corp"

curl -X POST https://api.unphurl.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","first_name":"Sarah"}'

unphurl https://suspicious-domain.xyz

curl "https://api.unphurl.com/v1/check?url=https://suspicious-domain.xyz" \
  -H "Authorization: Bearer uph_your_key_here"

# View packages
unphurl pricing

# Buy credits (opens Stripe checkout in your browser)
unphurl purchase pkg_100

curl -X POST https://api.unphurl.com/v1/purchase \
  -H "Authorization: Bearer uph_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"package":"pkg_100"}'

Check a URL

GET /v1/check?url={url}
Authorization: Bearer uph_your_key_here

Analyses a single URL. Returns signals, score, score breakdown, and metadata. Add ?profile=name to use a custom scoring profile.

Full pipeline response

{
  "url": "https://suspicious-domain.xyz/login",
  "final_url": "https://suspicious-domain.xyz/phish/page",
  "domain": "suspicious-domain.xyz",
  "score": 75,
  "score_breakdown": [
    { "signal": "brand_impersonation", "points": 40,
      "description": "impersonating paypal.com" },
    { "signal": "domain_age", "points": 35,
      "description": "domain registered 3 days ago" }
  ],
  "signals": {
    "url_analysis": {
      "url_length": 247,
      "path_depth": 3,
      "subdomain_count": 0,
      "domain_entropy": 3.1,
      "contains_ip": false,
      "encoded_hostname": false,
      "tld_changed_on_redirect": false
    },
    "redirects": {
      "chain": [
        "https://suspicious-domain.xyz/login",
        "https://suspicious-domain.xyz/redir",
        "https://suspicious-domain.xyz/phish/page"
      ],
      "count": 3,
      "initial_shortener": null,
      "stopped_reason": null
    },
    "domain": {
      "age_days": 3,
      "registrar": "NameCheap, Inc.",
      "expires_days": 362,
      "status_codes": ["clientTransferProhibited"],
      "nameservers": ["ns1.registrar-servers.com"],
      "has_mx_record": false,
      "is_parked": false,
      "is_known": false,
      "content_type": "text/html"
    },
    "ssl": { "valid": true },
    "phishing": {
      "is_phishing": true,
      "brand_impersonation": "paypal.com"
    }
  },
  "meta": {
    "checked_at": "2026-04-03T14:22:00Z",
    "latency_ms": 1240,
    "cached": false,
    "cache_age_hours": null,
    "pipeline_check_charged": true,
    "cache_ttl_remaining_hours": null
  }
}

Known domain response (free)

{
  "url": "https://google.com",
  "final_url": "https://www.google.com/",
  "domain": "google.com",
  "score": 0,
  "score_breakdown": [],
  "signals": {
    "domain": { "is_known": true, "is_parked": false },
    "ssl": { "valid": true },
    "phishing": { "is_phishing": false }
  },
  "meta": {
    "latency_ms": 45,
    "cached": false,
    "pipeline_check_charged": false
  }
}

Batch Check

POST /v1/check/batch
Authorization: Bearer uph_your_key_here
Content-Type: application/json

{
  "urls": [
    "https://google.com",
    "https://suspicious-domain.xyz",
    "https://bit.ly/abc123"
  ],
  "profile": "cold-email",
  "webhook_url": "https://your-server.com/results"
}

• Maximum 500 URLs per request. The CLI auto-chunks larger files. The MCP server handles polling automatically.
• Duplicates are silently deduplicated (process once, charge once).
• Invalid URLs get per-URL status: "error" without rejecting the batch.
• Known/cached URLs resolve immediately. Unknowns are queued for async processing.
• Optional: profile for custom scoring, webhook_url for delivery.

Response (with pending URLs)

{
  "results": [
    { "url": "https://google.com",
      "status": "complete",
      "result": { "...full response..." } },
    { "url": "https://suspicious-domain.xyz",
      "status": "pending" },
    { "url": "https://bit.ly/abc123",
      "status": "pending" }
  ],
  "summary": {
    "total": 3,
    "unique": 3,
    "duplicates_removed": 0,
    "complete": 1,
    "pending": 2,
    "errors": 0,
    "pipeline_checks_queued": 2
  },
  "job_id": "abc123-uuid-here",
  "poll_url": "/v1/jobs/abc123-uuid-here"
}

Job Polling

GET /v1/jobs/{job_id}
Authorization: Bearer uph_your_key_here

Poll for batch results. Job statuses: processing (still running) or completed (all done). Jobs expire after 24 hours.

{
  "job_id": "abc123-uuid-here",
  "status": "completed",
  "results": [
    { "url": "https://suspicious-domain.xyz",
      "status": "completed",
      "result": { "...full response..." } }
  ],
  "summary": {
    "total": 2,
    "completed": 2,
    "pending": 0,
    "failed": 0,
    "pipeline_checks_charged": 2
  }
}

pipeline_checks_charged counts only successful completions. Failed pipelines are not charged.

Webhooks

Include a webhook_url in your batch request. When the job completes, Unphurl POSTs the results to your URL. Same payload format as job polling.

Every webhook includes an X-Unphurl-Signature header (HMAC-SHA256 of the body, signed with your API key hash) for verification. 3 retries with exponential backoff (1s, 5s, 25s). Results are always available via polling too.

Filtering Results

After a batch check, you'll want to split results into clean and flagged lists. Two paths depending on your workflow.

CLI (developers)

# Get only clean URLs (score under 25)
unphurl --batch urls.txt --json | \
  jq -r '.results[] | select(.result.score < 25) | .url' > clean-urls.txt

# Get flagged URLs (score 50+)
unphurl --batch urls.txt --json | \
  jq -r '.results[] | select(.result.score >= 50) | .url' > flagged-urls.txt

# Export full results as CSV
unphurl --batch urls.txt --json | \
  jq -r '.results[] | [.url, .result.score, .result.domain, .result.signals.phishing.is_phishing] | @csv' > results.csv

Claude Cowork / MCP (non-coders)

Your AI is the filter. Give it the batch and tell it what you want:

Claude gets the batch results via MCP, filters them, and outputs the lists. No jq, no code. This is one of the moments where the non-coder experience is actually better than the developer experience.

Known Domain Check

GET /v1/known?domain=google.com

No authentication required. Returns whether a domain is in the Tranco Top 100K. Useful for predicting whether a check will be free.

{
  "domain": "google.com",
  "is_known": true,
  "source": "tranco_top_100k"
}

Account

POST /v1/signup
{ "email": "you@example.com", "first_name": "Sarah" }

POST /v1/verify/resend
{ "email": "you@example.com" }

{ "message": "If an account with that email exists and is not yet verified, a new verification link has been sent. Check your inbox." }

GET /v1/account    →    { "email": "...", "verified": true, "balance": 487 }

POST /v1/keys/rotate

DELETE /v1/account

GET /v1/history?page=1&limit=20

GET /v1/account/stats

{
  "usage": {
    "total_urls_submitted": 12450,
    "tranco_lookups": 8200,
    "cache_lookups": 3890,
    "pipeline_checks_run": 360,
    "free_rate_pct": 97.1
  },
  "scoring": {
    "checks_above_50": 142,
    "checks_above_75": 38
  },
  "account": {
    "credits_remaining": 145,
    "total_credits_purchased": 500,
    "last_active_at": "2026-04-08T14:30:00Z"
  }
}

Billing

GET /v1/balance

{
  "credits_remaining": 487,
  "total_purchased": 500,
  "total_used": 13,
  "free_lookups": 1042
}

POST /v1/purchase
{ "package": "pkg_500" }

GET /v1/pricing

Billing Behaviour

{
  "error": "insufficient_credits",
  "summary": {
    "total": 100,
    "tranco": 20,
    "cached": 30,
    "unknown": 50,
    "credits_needed": 50,
    "credits_remaining": 3
  },
  "message": "This batch has 50 unknown domains requiring pipeline checks. You have 3 credits. Purchase 47 more to run this batch.",
  "purchase_url": "/v1/purchase"
}

Scoring Profiles

Different use cases care about different signals. Profiles are sparse overrides merged with defaults. Up to 20 per account.

POST /v1/profiles
{
  "name": "cold-email",
  "weights": {
    "parked": 30,
    "chain_incomplete": 25,
    "no_mx_record": 20,
    "expiring_soon": 15,
    "ssl_invalid": 15,
    "http_only": 15,
    "brand_impersonation": 10,
    "domain_age_7": 5
  }
}

GET /v1/check?url=https://example.com&profile=cold-email

GET /v1/profiles

DELETE /v1/profiles/cold-email

Example profiles by use case

Scoring Weights

Default weights used when no profile is specified. Every weight can be overridden per profile.

How scores are calculated

1. Pipeline gathers raw signals across 7 dimensions
2. Each signal is checked against the weight table (default or your profile)
3. Domain age uses 4 mutually exclusive brackets (only the most specific fires)
4. Matching signals add their weight to the score
5. If 3+ signals fire, the compound amplifier adds its weight
6. If brand impersonation + any other signal, the phishing floor is enforced
7. score_breakdown in the response shows every contributing signal

Errors

Every error returns structured JSON with an error code and a human-readable message.

{
  "error": "insufficient_credits",
  "message": "No pipeline checks remaining. Purchase more to continue.",
  "credits_remaining": 0,
  "purchase_url": "/v1/purchase"
}

Rate Limits

Per API key. Designed to prevent bugs from burning credits, not to restrict normal use.

Rate limit headers in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. When limited, you get a 429 with a Retry-After header.

Comparison

Unphurl provides structured signals with configurable scoring. Unlike blocklist-based tools (Google Safe Browsing, VirusTotal), Unphurl analyses domain infrastructure in real time and catches threats too new for any database. Unlike enterprise tools (DomainTools, SecurityTrails), Unphurl requires no subscription and starts at $9. Unphurl also covers both security and data quality use cases, which none of the alternatives address with a single product.

See the full comparison chart on the homepage.

Limitations

• No safety guarantees. Heuristic detection catches patterns, not zero-day exploits or novel attacks.
• No page content scanning. Unphurl analyses the URL, domain, redirects, and TLS certificate. It does not load or render pages.
• No verdicts. No "block" or "allow" recommendations. Signals and scores only. Your AI agent decides.
• No third-party threat databases. Own heuristic analysis only. Catches pattern-based threats too new for databases.
• Tranco Top 100K trusted. Known domains return score 0 without pipeline. If compromised, Unphurl will not catch it.
• RDAP data can be incomplete. Some registries don't support RDAP. Domain age returns null when unavailable.

CLI Quick Start

Check URLs from the terminal. Colour-coded scores, JSON output, batch processing, full account management.

npx unphurl https://suspicious-domain.xyz

unphurl --batch urls.txt --profile cold-email

unphurl https://example.com --json | jq '.score'

# Sign up
unphurl signup --email you@example.com --name "Your Name"

# Resend verification email
unphurl verify --resend --email you@example.com

# Check balance
unphurl --balance

# View usage statistics
unphurl stats

# Buy credits
unphurl purchase pkg_500

# Manage profiles
unphurl profiles create cold-email --weights '{"parked":30,"ssl_invalid":15}'
unphurl profiles

export UNPHURL_API_KEY=uph_your_key_here

MCP Quick Start

Native integration with Claude (Code, Desktop, or Cowork), ChatGPT desktop, Cursor, Windsurf, and any MCP-compatible AI tool. 13 tools with full API parity.

{
  "mcpServers": {
    "unphurl": {
      "command": "npx",
      "args": ["-y", "@unphurl/mcp-server"],
      "env": {
        "UNPHURL_API_KEY": "uph_your_key_here"
      }
    }
  }
}

cp node_modules/@unphurl/mcp-server/skills/check-url-safety.md ~/.claude/skills/