Haunt API Docs: MCP Server and REST API Reference

start here

Pick one path. Do not read the whole page first.

New users should make one safe extraction before browsing the reference. The rest of this page is split into demo response, free key, first call, MCP setup, and REST reference.

Demo response

Open the fixed no-key demo to inspect response shape before signup.

Free key

Create a free key from signup, then save it once. No card needed for the free tier.

First call

Run the 60-second cURL request against https://example.com. Building an agent? Use the focused agent path.

first call

First extraction in 60 seconds.

This is the shortest safe path from signup to a real JSON response. Do this before wiring Haunt into production code.

Copy your API key

Create a free key from the signup form, then save it once. Haunt only shows it at creation time.

Run one safe test

Use https://example.com first so you can verify auth, JSON parsing, and trace output without a difficult target page.

Check `success` before using `data`

A clean failure is part of the contract. Branch on success:false, error_code, and trace instead of trusting empty fields.

first-call curl

curl -X POST https://hauntapi.com/v1/extract \
  -H "X-API-Key: PASTE" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","prompt":"Return the page title and main heading as JSON"}'

Need a key first? Get your free API key, then come back here.

No key yet? Start with the fixed no-key demo, then create a free key from signup. If you are building an agent, use the focused agent path.

mcp setup

Connect your AI tool.

Fastest path: use hosted HTTP MCP at https://hauntapi.com/mcp/server. Local-client path: run the published @hauntapi/mcp-server package with npx. Both use the same extraction service underneath.

Security: real extraction requires a direct Haunt key in Authorization: Bearer <key> or X-API-Key. The hosted MCP demo/list path is rate limited before a key is supplied. RapidAPI subscriber headers are not accepted on hosted MCP. /mcp is discovery JSON only. Do not use /sse.

hosted HTTP MCP config

{
  "mcpServers": {
    "haunt": {
      "url": "https://hauntapi.com/mcp/server",
      "headers": { "Authorization": "Bearer ${HAUNT_API_KEY}" }
    }
  }
}

Claude Desktop

Cursor

Windsurf

VS Code

OpenCode

claude_desktop_config.json

{
  "mcpServers": {
    "haunt": {
      "command": "npx",
      "args": ["-y", "@hauntapi/mcp-server"],
      "env": { "HAUNT_API_KEY": "PASTE" }
    }
  }
}

.cursor/mcp.json

{
  "mcpServers": {
    "haunt": {
      "command": "npx",
      "args": ["-y", "@hauntapi/mcp-server"],
      "env": { "HAUNT_API_KEY": "PASTE" }
    }
  }
}

.windsurf/mcp.json

{
  "mcpServers": {
    "haunt": {
      "command": "npx",
      "args": ["-y", "@hauntapi/mcp-server"],
      "env": { "HAUNT_API_KEY": "PASTE" }
    }
  }
}

settings.json

{
  "mcp": {
    "servers": {
      "haunt": {
        "command": "npx",
        "args": ["-y", "@hauntapi/mcp-server"],
        "env": { "HAUNT_API_KEY": "PASTE" }
      }
    }
  }
}

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "haunt": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@hauntapi/mcp-server"],
      "env": { "HAUNT_API_KEY": "PASTE" },
      "enabled": true
    }
  }
}

tools

Available MCP tools.

Tool	Description	Key parameters
`try_demo_extract`	Inspect fixed sample output before signup. No remote fetch, no provider call, no key.	None
`extract`	Extract structured data from permitted public URLs.	`url`, `prompt`
`get_usage`	Check remaining credits and plan information.	API key in header

ask your AI

// "Run try_demo_extract so I can see Haunt's response shape"
// "Get the current price from this product page"
// "Pull company name, services and contact routes from this site"

rest api

POST a URL. Get clean JSON.

Include your API key in X-API-Key. Bearer auth also works through Authorization.

POST /v1/extract

Prefer Postman? Download the maintained Haunt API Postman collection.

curl request

curl -X POST https://hauntapi.com/v1/extract   -H "X-API-Key: PASTE"   -H "Content-Type: application/json"   -d '{
    "url": "https://example.com",
    "prompt": "Extract the page title"
  }'

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The URL to extract data from.
`prompt`	string	Yes	What to extract, in plain English.
`cookies`	object	No	Use with `/v1/extract/auth` on Pro and Scale only.
`headers`	object	No	Use with `/v1/extract/auth` on Pro and Scale only.

Example

Python

JavaScript

cURL

python

import requests

resp = requests.post(
    "https://hauntapi.com/v1/extract",
    headers={"X-API-Key": "PASTE"},
    json={
        "url": "https://news.ycombinator.com",
        "prompt": "Get the top 5 stories with titles and points"
    },
    timeout=60,
)
if not resp.ok:
    raise SystemExit(f"HTTP {resp.status_code}: {resp.text}")
payload = resp.json()
if not payload.get("success"):
    raise SystemExit(payload.get("error") or payload.get("error_code") or "Extraction failed")
print(payload["data"])

javascript

const response = await fetch("https://hauntapi.com/v1/extract", {
  method: "POST",
  headers: { "X-API-Key": "PASTE", "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://news.ycombinator.com", prompt: "Get the top 5 stories" })
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const payload = await response.json();
if (!payload.success) throw new Error(payload.error || payload.error_code || "Extraction failed");
console.log(payload.data);

curl

curl -X POST https://hauntapi.com/v1/extract   -H "X-API-Key: PASTE"   -H "Content-Type: application/json"   -d '{"url":"https://news.ycombinator.com","prompt":"Get the top 5 stories"}'

Trust Trace

Every response includes evidence.

Haunt returns a safe trace object that explains the fetch path, extraction confidence, mode, and summary without exposing raw HTML, cookies, headers, prompts, or API keys.

fetch

Source

Direct, proxy, fallback fetch, or browser render.

extract

Mode

Structured extraction with confidence score.

quota

Credits

Remaining requests and token usage.

summary

Readable proof

A short explanation of what happened.

limits

Rate limits.

Plan	Successful requests/month	Rate limit	Feature gate
Free	100	10 req/min	Public pages only
Starter	5,000	30 req/min	Public pages only
Pro	25,000	60 req/min	Authenticated extraction
Scale	75,000	120 req/min	Authenticated extraction and batch

If you receive 429 Rate limit exceeded, read Retry-After, wait that many seconds, then retry with exponential backoff. Haunt does not bill automatic overages.

errors

CAPTCHA-aware failures.

Failed extractions do not count against your quota. When extraction fails, Haunt returns structured machine-readable fields so automation can branch safely.

Bad first request fixes.

Most first-call failures are setup issues, not extraction problems. Use X-API-Key, start with https://example.com, then branch on error_code.

401

`missing_api_key`

No key was sent. Add X-API-Key or Authorization: Bearer, or create a free key from signup.

401

`invalid_api_key`

The key did not match an active account. Copy it exactly, or regenerate a key if the original was lost.

422

`invalid_request`

The body is malformed. URLs must start with http:// or https://. Safe test: {"url":"https://example.com","prompt":"Extract the page title"}.

429

`rate_limit_exceeded` or `monthly_quota_exceeded`

Per-minute limits return Retry-After. Monthly quota errors mean the plan allowance is used, so upgrade or wait for reset.

200

`not_found`

No matching data was visible in the fetched page. Try a narrower prompt, a more specific URL, or a page where the requested facts are actually shown. Check trace and evidence before retrying.

200

`login_required`

The target redirected to a login wall before exposing data. Use a public URL, authorised session handoff, or a source/feed you are allowed to access.

200

`access_denied`

The target returned an edge or platform access-denied page. Haunt fails closed instead of inventing results.

200

`thin_public_content`

The page loaded, but not enough public content was visible for the requested listing/product data. Try an item-detail URL or a more stable allowed source.

not found response

{
  "success": false,
  "error": "Could not find requested data in the page content",
  "error_code": "not_found",
  "mode": "not_found",
  "confidence": 0.0,
  "url": "https://example.com",
  "trace": {
    "extraction": { "mode": "not_found", "confidence": 0.0 },
    "checks": [
      { "name": "content_visibility", "status": "not_found" }
    ]
  }
}

human verification response

{
  "success": false,
  "error": "CAPTCHA required: the target page requires human verification.",
  "error_code": "captcha_required",
  "captcha_provider": "hcaptcha",
  "requires_human_verification": true,
  "url": "https://example.com",
  "mode": "captcha_required",
  "trace": {
    "fetch": { "source": "playwright", "status_code": 200 },
    "extraction": { "mode": "captcha_required", "confidence": 0.0 },
    "checks": [
      { "name": "human_verification", "status": "blocked" }
    ]
  }
}

Implementation detail: Haunt does not auto-handle CAPTCHA challenges. It detects and reports them with explicit machine-readable flags so clients can route to a human flow.

If your first real target fails, do not debug the hard site first. Run the safe https://example.com first-call, then compare against the demo response shape. Clean failures are expected on CAPTCHA, login-only, or thin public pages.

start scanning

Get 100 free requests and point Haunt at the web.

No credit card required for the free tier. Paid plans start at 5,000 successful requests/month.

Get your free API key