Skip to content
MarketHQ

API and MCP docs

Query your market intelligence from your own agents, scripts, and tools: the same reads that power chat, over a real REST API and an MCP server.

Authentication

Every request, REST or MCP, needs the same key.

An API key looks like mhq_ followed by a random string. Create one signed in, at /app/mcp-api → “Your API keys”, scoped read-only or read + write, with an optional expiry. The full key is shown once, at creation.

Send it as a bearer token on every request, including an MCP initialize call:

Authorization: Bearer <YOUR_API_KEY>

A missing or invalid key gets HTTP 401. A key that lacks the scope a route needs (report outcomes, claim a task) gets 403.

Which plans get access

Every paid plan, including an active trial.

Lite, Startup, and Growth all get the REST API and MCP server. Paid tiers differ by tracking capacity, not by which surfaces are on. Lite and Startup start with a 7-day trial for $0.99; a workspace on that trial is fully entitled, the same as a paying one.

The free plan does not get API/MCP access. A key created on a free workspace, or a paid workspace that lapses, gets HTTP 402 on every call until the workspace is on a paid plan.

REST API

Base URL: https://markethq.ai/api/v1. Every response carries data plus as_of and freshness ("live" | "rollup" | "weekly"), so you can tell a live read apart from a weekly rollup.

Read endpoints

GET/mentions?source=&days=&limit=&since=&cursor=&includeNoise=

Collected mentions (developer communities, blogs and feeds, plus social and web sources on paid plans), newest first. audience: "noise" mentions (status bots, SEO farms, competitor marketing) are excluded by default — pass includeNoise=true to include them.

curl "https://markethq.ai/api/v1/mentions" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/signals?signal=&days=&limit=&since=&cursor=&includeNoise=

Derived opportunity/revenue/risk/mention signals, newest-derived first. signal=noise rows are excluded by default — pass signal=noise explicitly or includeNoise=true to include them.

curl "https://markethq.ai/api/v1/signals" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/ai-visibility

Current-week AI-answer-engine visibility share vs. tracked competitors.

curl "https://markethq.ai/api/v1/ai-visibility" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/gaps

The latest weekly gap analysis + action plan (404 until the first weekly report has run).

curl "https://markethq.ai/api/v1/gaps" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/intelligence?dateFrom=&dateTo=&brand=&category=&levers=&limit=&grouped=&clustered=&since=&cursor=

Prioritized themes ranked by volume across four levers (acquisition, retention, learning, advocacy), per brand, in a date window.

curl "https://markethq.ai/api/v1/intelligence" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/agent-brief?includePeers=&since=&cursor=&limit=

One call: what's urgent, what to do next, who to talk to — buyers-only by default. The REST twin of the MCP get_agent_brief tool; same assembly, same data.

curl "https://markethq.ai/api/v1/agent-brief" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/listicles

Which list-format pages rank top-10 for your tracked category keywords, which the week's AI answers cite, whether you're listed, and the ranked "get listed here" action list.

curl "https://markethq.ai/api/v1/listicles" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/tasks?status=&limit=&cursor=

Actionable tasks, each with a playbook (concrete steps, a done check, expected impact), priority first.

curl "https://markethq.ai/api/v1/tasks" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/tasks/:id

Full detail for one task: its playbook and up to three pieces of evidence.

curl "https://markethq.ai/api/v1/tasks/:id" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/content-opportunities?kind=&limit=

Questions developers, Google and AI engines ask in your category, and keywords you can rank for — each with the evidence behind it and a deterministic id. Pass an id to POST /content-outline for a ready-to-write outline.

curl "https://markethq.ai/api/v1/content-opportunities" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
GET/keyword-gaps?limit=

Competitor pages you're missing: pages that rank for your tracked keywords while you don't, whether that's a competitor's own page, a list that names one, or another site outranking you. Each comes with its rank, keywords and the competitors it's evidence against (empty for other sites).

curl "https://markethq.ai/api/v1/keyword-gaps" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Write endpoints

2 of 3 need a key with the write scope; /content-outline only needs read, since it caches a generated result rather than mutating anything.

POST/outcomes

Report what happened after acting on a surfaced opportunity or action: sent -> replied -> meeting -> closed_won ($) | closed_lost | dismissed. The REST twin of the MCP report_outcome tool.

curl -X POST "https://markethq.ai/api/v1/outcomes" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"actionId":"<ACTION_ID>","stage":"closed_won","amountUsd":4800}'
POST/tasks/:id/claim

Claim a task so a teammate (human or agent) doesn't duplicate the work. Race-safe: the same agentName re-claiming is a no-op success; a different agentName on an already-claimed task gets 409 already_claimed, never a silent takeover. That exclusivity is keyed on agentName — pass a real, distinct one, or every caller shares the same 'unnamed' identity and can all re-claim the same task.

curl -X POST "https://markethq.ai/api/v1/tasks/<ID>/claim" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"agentName":"<YOUR_AGENT_NAME>"}'
POST/content-outline

A ready-to-write outline (title, angle, target keyword, audience, sections, FAQ, evidence to cite, CTA) for one content opportunity from GET /content-opportunities. The first generation for a given id counts against this workspace's monthly outline allowance (the response's remaining/limit fields track it); re-opening an outline already generated — from a previous call, the app, or MCP — is free and never counts again. The REST twin of the MCP get_content_outline tool. Needs a body (the opportunity id) like the write endpoints above, but reads with a plain 'read' key — it caches a generated result rather than mutating anything a customer manages.

curl -X POST "https://markethq.ai/api/v1/content-outline" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id":"<OPPORTUNITY_ID>"}'

MCP server

Endpoint: https://markethq.ai/api/mcp. Streamable HTTP transport, stateless JSON-RPC 2.0 (no session id; a GET request returns 405). Same bearer key as the REST API, required on every request including "initialize". The one exception is "ping", which the spec allows without a key.

Claude Desktop

{
  "mcpServers": {
    "markethq": {
      "url": "https://markethq.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Claude Code

claude mcp add --transport http markethq https://markethq.ai/api/mcp --header "Authorization: Bearer <YOUR_API_KEY>"

Cursor

{
  "mcpServers": {
    "markethq": {
      "url": "https://markethq.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Generic HTTP

curl -X POST "https://markethq.ai/api/mcp" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Tools

  • search_mentionsSearch this workspace's collected mentions (developer communities, blogs and feeds, plus social and web sources on paid plans).
  • list_signalsList this workspace's derived opportunity/revenue/risk/mention signals, newest-derived first.
  • get_ai_visibilityThis workspace's current-week AI-answer-engine visibility share vs.
  • get_gap_reportThe latest weekly gap analysis + action plan for this workspace.
  • get_prioritiesThis workspace's prioritized intelligence feed: classified mentions grouped into themes and ranked by volume across four levers — acquisition (unhappy competitor customers = takeover), retention (complaints about you), learning (competitor pricing/features), advocacy (testimonials for you).
  • get_agent_briefOne call, everything you need to work this workspace today: what is urgent, what to do next, who to talk to, and what was deliberately left out.
  • get_agent_brief_deltaThe same brief as get_agent_brief, narrowed to what arrived after `cursor` — for a repeat poll when you already worked everything earlier.
  • report_outcomeClose the loop: after you act on an opportunity or action surfaced by get_priorities or get_gap_report, report what actually happened so this workspace's funnel and reported pipeline reflect it.
  • get_evidenceLook up the source evidence (title, url, source, published date, excerpt) for mention ids you already hold — from a citation, a theme's mentionIds, or an action's evidence — to double-check a quote before acting on it.
  • describe_freshnessThis workspace's data cadence in plain terms: when mentions were last refreshed, when the intelligence feed was last recomputed from them, when AI answers were last sampled, and when the weekly gap report was last built.
  • list_tasksList this workspace's tasks — actionable items, each with a playbook attached (concrete steps, a done check, and expected impact).
  • get_taskFull detail for one task: its playbook (steps, a done check, expected impact) and up to three pieces of evidence.
  • claim_taskClaim a task so a teammate (human or agent) doesn't duplicate the work.
  • get_content_opportunitiesWhat to write next: questions developers, Google and AI engines ask in this workspace's category, and keywords it can rank for — each with the evidence behind it (source quotes/links, who already ranks or answers it) and a deterministic id.
  • get_content_outlineA ready-to-write outline (title, angle, target keyword, audience, sections, FAQ, evidence to cite, CTA) for one content opportunity from get_content_opportunities.
  • get_keyword_gapsCompetitor pages you're missing: pages that rank for this workspace's tracked keywords while it doesn't, whether that's a competitor's own page, a listicle naming one, or another site outranking it.

Rate limits

Per API key, not per workspace.

120 requests per key per one-minute window, on REST and MCP alike. Over the limit gets HTTP 429 with a Retry-After header naming the seconds until the window rolls over.

Building an agent that reads this whole site’s content programmatically? See /llms.txt.