# App Pain API

> Mine iOS/Android/macOS app-store reviews, WordPress plugin reviews and Chrome extension reviews into ranked, evidence-backed pain points — share %, severity, verbatim quotes. Remote MCP server + REST API + Agent Skill. Free tier with no key for light use; ~124 popular apps, plugins and extensions pre-analyzed with a 7-day cache.

App Pain API turns app-store negative reviews into structured competitive intelligence: LLM-clustered pain points with sharePercent, severity and verbatim evidence quotes, comparable across competitors and over time. Usable from any AI chat (paste-one-prompt install), terminal (Agent Skill), or code (REST).

## Endpoints

- [MCP server](https://hawkmill.com/mcp): remote MCP over streamable HTTP, no authentication for light use
- [REST API](https://hawkmill.com/docs): same data over plain HTTP, JSON in / JSON out
- [Pain index](https://hawkmill.com/pains): the pre-analyzed popular apps, browsable without a key
- [Status](https://hawkmill.com/status): upstream health canary, updated hourly

## Install

- MCP: paste "Install the \"app-pain-api\" MCP server — remote HTTP, URL: https://hawkmill.com/mcp, no authentication needed." into Claude / ChatGPT / Cursor / Windsurf / Codex — the AI handles installation
- REST: `curl -s "https://hawkmill.com/v1/apps/android/com.spotify.music/painpoints" | jq`

## Tools (7, via MCP tools/list or REST)

- search_apps: find appIds by keyword across Google Play / App Store / WordPress.org / Chrome Web Store / Steam — always step 1
- mine_app_pain_points: the core tool — clustered pain points with share %, severity, verbatim evidence (7-day cache; cold analysis 30-170s, cached results in seconds)
- get_app_reviews: raw reviews, 50/page, unified schema across both stores (rating/title/body/version/date/devReply/thumbsUp)
- get_pain_trend: how pain points drift day over day — what is getting worse or getting fixed
- get_version_history: per-release review stats — spot a rating crash right after a bad release
- get_app_details: rating history, version info
- watch_competitors: ongoing monitoring — new 1-2 star reviews and rising pain points pushed to Slack/Discord/webhooks (paid plans)

## Prompts (2)

- competitor_pain_report: category-wide competitor pain report, e.g. "habit tracker"
- app_pain_deep_dive: single-app deep dive from a name, store URL or id

## Auth

- Keyless: unlimited cached results + a few fresh analyses per day — nothing to configure
- Free key (10 analyses/mo + 10 signup bonus): POST https://hawkmill.com/v1/register {"email"} → POST /v1/verify {"email","code"} with the emailed code. Save the returned key to ~/.app-pain/api_key (the verify response includes the exact command)
- REST: pass the key as the x-api-key header. Paid plans: https://hawkmill.com/buy

## Notes for agents

- Cold analyses stream SSE heartbeats to survive 170s tool timeouts; set client timeouts >= 180s
- Default reviews:300 works for iOS/macOS too (deep pages fetch via relay); Apple rate limiting can occasionally cap depth; if painPoints comes back empty, retry with maxRating:5
- Direct connection works worldwide, mainland China included