# URL Intelligence API — resolve any URL to its final/clean URL, classify the entity type, find the canonical domain and route it to the right data engine

> Any URL → final_url, cleaned_url (tracking stripped), domain, entity_type{value,confidence,source}, platform, recommended{engine,action,params} (the Reef deep-fetch card; web-extract fallback for unknown hosts), tracking{affiliate,stripped_params}.
> ReefAPI engine `enrich-url` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/enrich-url/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /enrich-url/v1/classify — 2 credits
Any URL → final_url, cleaned_url (tracking stripped), domain, entity_type{value,confidence,source}, platform, recommended{engine,action,params} (the Reef deep-fetch card; web-extract fallback for unknown hosts), tracking{affiliate,stripped_params}.

**Parameters:**
- `url` (string, required) — Any http(s) URL — short/affiliate/tracking/canonical — or a bare host (stripe.com). Redirects are followed + tracking stripped by the inner url-resolver (SSRF-guarded). Private/internal targets are blocked there.
- `deep` (boolean, optional, default false) — Advanced: when true, run an additional structured-data pass even when the page type was already identified, for deeper detail. Default false = fastest, most cost-efficient path.

**Returns:** input_url, final_url, cleaned_url, canonical_url, domain, registrable_domain, is_short_link, redirect{redirected,hops,chain_hosts}, entity_type{value,confidence,source}, platform, identifier, recommended{engine,action,params} (null→web-extract fallback card), tracking{is_affiliate,affiliate_network,merchant_hint,stripped_params[]}, preview{title,description,image,site_name,og_type}, provenance{resolver,classifier status+missing_reason}, meta.extra.subcalls[]

**Example request body:**
```json
{
  "url": "https://www.amazon.com/dp/B08N5WRWNW?tag=aff-20&utm_source=x"
}
```

### POST /enrich-url/v1/extract_entity — 2 credits
Any URL → a lightweight entity card with title, image, description, price, author and publication date — great for link previews and deciding which Reef engine to call next. Use the recommended{} field from classify for the full deep-fetch.

**Parameters:**
- `url` (string, required) — Any http(s) URL — short/affiliate/tracking/canonical — or a bare host (stripe.com). Redirects are followed + tracking stripped by the inner url-resolver (SSRF-guarded). Private/internal targets are blocked there.

**Returns:** final_url, domain, entity_type{value,confidence,source}, platform, entity{title,name,image,description,price,currency,author,published_at,site_name,canonical}, recommended{engine,action,params}, source (og|jsonld|resolver-preview|web-extract), provenance

**Example request body:**
```json
{
  "url": "https://github.com/torvalds/linux"
}
```

### POST /enrich-url/v1/batch — 2 credits
Classify up to 20 URLs in one call (the link-list cleanup + routing use-case): per-URL ok/error, each independently resolved + classified.

**Parameters:**
- `urls` (array, required) — Up to 20 URLs (array or comma-separated). Each is resolved + classified independently; per-URL ok/error.

**Returns:** results[] (one classify payload or {ok:false,error} per input), count, ok_count

**Example request body:**
```json
{
  "urls": [
    "https://x0.example",
    "https://x1.example",
    "https://x2.example",
    "https://x3.example",
    "https://x4.example",
    "https://x5.example",
    "https://x6.example",
    "https://x7.example",
    "https://x8.example",
    "https://x9.example",
    "https://x10.example",
    "https://x11.example",
    "https://x12.example",
    "https://x13.example",
    "https://x14.example",
    "https://x15.example",
    "https://x16.example",
    "https://x17.example",
    "https://x18.example",
    "https://x19.example",
    "https://x20.example"
  ]
}
```

### POST /enrich-url/v1/catalog_resolve — 1 credit
META (no network): given a known platform name OR a URL's host, return which Reef engine+action handles it and the param key it needs — the routing table itself (url-resolver marketplace engine_hints + the non-marketplace platform map). For agents discovering 'which engine for X'.

**Parameters:**
- `platform` (string, optional) — A platform name (instagram/youtube/github/amazon/…) to resolve to its Reef engine+action. Omit both platform and url to list the full table.
- `url` (string, optional) — Optional URL whose host is mapped to its Reef engine (no network fetch — host-only routing lookup).

**Returns:** query, matched (bool), platform, entity_type, recommended{engine,action,param_key}, known_platforms[] (when no query: the full routing table)

**Example request body:**
```json
{
  "platform": "instagram"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=enrich-url
- Human docs page: https://reefapi.com/docs/enrich-url
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt