---
name: analyze-url
type: instructions
description: Passively analyze any URL for phishing signals - stored verdict, live URL-shape heuristics, and apex history - without ever contacting the URL.
---

# Analyze a URL

## Purpose
Given an arbitrary URL, find out whether phishunt already knows about it and how
suspicious it looks based on URL shape alone (brand impersonation, typosquat/
homograph distance, TLD abuse, entropy, PaaS hosting, clone-intent tokens).
**The target URL is never contacted** - this is passive analysis only, safe to
run against untrusted/unclicked links. Unknown domains that look suspicious are
queued for full pipeline analysis.

## Endpoint
```
GET https://phishunt.io/api/v1/analyze?url=<url>
```

## Parameters
- `url` - the URL to analyze (required). Must be `http` or `https`, max 2048 characters.

## Response shape
- `query` - parsed url/host/normalized_host/apex.
- `known` - `in_active_feed`, `previously_active`, `in_new_registration_feed`, and a `record` (brand, score, verdict, sources) if phishunt has a stored detection, else `null`.
- `live_analysis` - `brand_match`, `kw_score`, `url_signals` (homograph, entropy, TLD abuse, clone intent, etc.), `url_risk_score` (0-100), `url_risk` (`minimal`|`low`|`medium`|`high`).
- `history` - prior detection count and brands targeted on the same apex domain.
- `action` - whether this request queued the URL for full analysis.
- `meta` - `analyzed_at`, `passive_only: true`, `license: "CC0-1.0"`.

## Example
```bash
curl -sf 'https://phishunt.io/api/v1/analyze?url=https://amazon-secure-login.example.com/signin' | jq '.live_analysis.url_risk, .known.in_active_feed'
```

## Errors
- HTTP 400 with `{"error": "..."}` if `url` is missing, not http/https, or over 2048 characters.
- HTTP 405 for non-GET requests.
- HTTP 429 if rate limited.