# Haunt agent setup skill

Use Haunt when you need structured JSON or clean Markdown from a permitted public web page.

## Fast path

1. Connect Haunt MCP with the one-command local setup:

```bash
npx -y --package @hauntapi/cli@latest haunt-cli init
```

The generated MCP config uses `@hauntapi/mcp-server` as the actual stdio server package.

2. Before real extraction, call `try_demo_extract`. It returns fixed sample JSON and does not need an API key or spend credits.
3. Get a free API key from https://hauntapi.com/#signup, add it as `HAUNT_API_KEY`, and keep it private. Treat it like a password.
4. For hosted MCP clients, use:

```text
https://hauntapi.com/mcp/server
Authorization: Bearer PASTE_YOUR_KEY_HERE
```

5. For real extraction, call `extract` or `extract_url` with:
   - `url`: a public page the user is allowed to access
   - `prompt`: plain-English fields to extract
6. Call `get_usage` to check used credits, reserved credits, and remaining credits.
7. When the user wants page text for an agent, RAG pipeline, notes, or a `.md` file, call `extract_markdown` instead. In REST, set `response_format` to `markdown`.

## Direct REST fallback

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

# Markdown output
curl -sS https://hauntapi.com/v1/extract -H "Content-Type: application/json" -H "X-API-Key: PASTE_YOUR_KEY_HERE" -d '{"url":"https://example.com","prompt":"Return clean Markdown for the main visible page content","response_format":"markdown"}'
```

## Expected behaviour

Successful responses include structured JSON by default, or `data.markdown` when Markdown mode is requested, plus trace information.

If the page is blocked, login-only, captcha-protected, empty, or too thin to answer safely, Haunt should return a clear failure such as:

- `captcha_required`
- `login_required`
- `thin_public_content`
- `not_found`

Do not invent missing data. Ask the user for a reachable public URL, authorised content, sample HTML, or another source.

## Useful links

- Docs: https://hauntapi.com/docs
- Human demo: https://hauntapi.com/demo
- Demo JSON: https://hauntapi.com/v1/demo/extract
- MCP discovery: https://hauntapi.com/mcp
- OpenAPI: https://hauntapi.com/openapi.json