API Documentation

Everything your own AI agent, n8n workflow or script needs to run the reply loop from your account: hot leads with drafts and posting guidance, mark replied, skip, the Reddit reply budget and the Citation Share scoreboard. Plus mentions and keywords. All endpoints require an API key.

Authentication

All API requests require a Bearer token. Generate your API key in Settings → API.

Authorization: Bearer hm_your_key_here

API keys start with hm_. Keep them secret — they grant full access to the project they are bound to.

Keys are bound to a project. You pick the project when you create the key, and every call acts on that project. If the key's owner can access several projects, pass project_id (query string or JSON body) to act on another one; a project you cannot access answers 403, and a key with no project answers 404 until you bind one. Requests are limited to 60 per minute per key.

Base URL

https://hotmention.com/api/v1

Prefer MCP or a CLI? The same actions are available as eleven MCP tools and as the hotmention command-line client — see the Autopilot guide.

The reply loop

Leads are the mentions worth acting on. A lead object looks like this everywhere below:

{
  "id": "lead_8f2k",
  "platform": "REDDIT",
  "url": "https://www.reddit.com/r/Emailmarketing/comments/1n4x.../",
  "title": "Looking for an email warmup tool that doesn't get my domain flagged",
  "content": "We're ramping up cold outreach next month and I'm worried about deliverability...",
  "author": "deliverability_dan",
  "subreddit": "Emailmarketing",
  "score": 87,
  "scoreLabel": "HOT",
  "sentiment": "NEUTRAL",
  "shouldReply": "REPLY",
  "shouldReplyReason": "Owns the problem and is actively comparing tools",
  "draftReply": "Been through this exact pain — most warmup tools blast obvious template threads...",
  "matchedKeyword": "email warmup",
  "pipelineStage": "NEW",
  "postedAt": "2026-09-11T08:30:00.000Z",
  "foundAt": "2026-09-11T08:41:12.000Z",
  "repliedAt": null,
  "replyUrl": null,
  "replyHealth": null,
  "aiCited": false,
  "citedForPrompts": [],
  "survivalScore": 78,
  "postingGuidance": {
    "level": "ok",
    "rules": [
      "Answer the question first; name the product once, as an aside",
      "No link unless someone asks for one"
    ],
    "note": null,
    "survivalScore": 78
  }
}

· postingGuidance.level is ok, careful or avoid; rules lists what to follow on careful. Do not post where it says avoid.
· replyHealth after you reply: PENDING (verifying), LIVE, REMOVED, UNKNOWN (three failed checks) or NOT_VERIFIED (X and other platforms).
· aiCited marks Reddit threads that ChatGPT, AI Overviews, Perplexity or Claude cite for your buying prompts; citedForPrompts says which. They are WARM by design, never HOT.

GET/api/v1/leads

HOT leads waiting in NEW that are worth a reply, best first, with the current Reddit reply budget.

🔑 Requires Authorization: Bearer hm_your_key

Query Parameters

hot0 | 1— 1 (default) returns HOT only; 0 adds WARM mentions

platformstring— REDDIT, TWITTER, LINKEDIN, QUORA, THREADS, YOUTUBE

sinceISO date— Only leads found after this (default: last 72h)

limitnumber— 1-100 (default 20)

include_ai_cited0 | 1— Also return AI-cited threads (WARM, strategic, not urgent)

project_idstring— Act on another project the key's owner can access

Example

curl "https://hotmention.com/api/v1/leads?platform=REDDIT&since=2026-09-10T00:00:00Z" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{
  "leads": [ { "id": "lead_8f2k", "scoreLabel": "HOT", "score": 87, "...": "see the lead object above" } ],
  "total": 3,
  "budget": {
    "dailyCap": 3,
    "weeklyCap": 10,
    "usedToday": 1,
    "usedWeek": 4,
    "remainingToday": 2,
    "remainingWeek": 6,
    "exhausted": false,
    "lastRepliedAt": "2026-09-11T07:20:00.000Z",
    "nextSuggestedAt": "2026-09-11T08:20:00.000Z"
  },
  "project": { "id": "prj_123", "name": "Warmhound" }
}

GET/api/v1/leads/{id}

The full card for one lead, including the draft, reply status and posting guidance.

🔑 Requires Authorization: Bearer hm_your_key

Example

curl "https://hotmention.com/api/v1/leads/lead_8f2k" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{ "lead": { "id": "lead_8f2k", "...": "the lead object" } }

POST/api/v1/leads/{id}/draft

Regenerate the draft reply on demand, optionally steered by instructions. Works for HOT, WARM and LOW leads; counts against the draft quota on limited plans.

🔑 Requires Authorization: Bearer hm_your_key

Request Body (JSON)

instructionsstring— e.g. "mention the free tier, no link" (up to 500 characters)

project_idstring— Act on another project

Example

curl -X POST "https://hotmention.com/api/v1/leads/lead_8f2k/draft" \
  -H "Authorization: Bearer hm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "mention the free tier, no link"}'

Response

{ "lead": { "id": "lead_8f2k", "draftReply": "Been through this exact pain — ...", "...": "the lead object" } }

POST/api/v1/leads/{id}/replied

Record that you posted a reply from your own account. Pass the comment permalink so HotMention can verify it on day 1, 3 and 7. Idempotent: a second call returns idempotent: true and changes nothing. A Reddit lead past the reply budget answers 409 budget_exhausted unless force is true.

🔑 Requires Authorization: Bearer hm_your_key

Request Body (JSON)

reply_urlstring— Permalink to the comment you posted (Reddit comment permalink for exact verification)

accountstring— Username/handle the reply was posted from

sourcestring— Free-form origin label, e.g. "n8n" (default "api")

forceboolean— Record even when the Reddit budget is exhausted

project_idstring— Act on another project

Example

curl -X POST "https://hotmention.com/api/v1/leads/lead_8f2k/replied" \
  -H "Authorization: Bearer hm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"reply_url": "https://www.reddit.com/r/Emailmarketing/comments/1n4x.../k3j9x2m/", "account": "your_reddit_name"}'

Response

{
  "lead": { "id": "lead_8f2k", "pipelineStage": "REPLIED", "replyHealth": "PENDING", "replyUrl": "https://www.reddit.com/r/.../k3j9x2m/", "...": "the lead object" },
  "idempotent": false,
  "budget": { "dailyCap": 3, "usedToday": 2, "remainingToday": 1, "exhausted": false, "nextSuggestedAt": "2026-09-11T09:41:12.000Z", "...": "" },
  "hint": null
}

// 409 when the Reddit budget is used up
{ "error": "Reddit reply budget exhausted: 3 of 3 today. Wait, or pass force.", "code": "budget_exhausted", "budget": { "...": "" } }

POST/api/v1/leads/{id}/skip

Skip a lead with an optional reason. Skipped leads leave the queue and never count as billable.

🔑 Requires Authorization: Bearer hm_your_key

Request Body (JSON)

reasonstring— Why, for your own records

project_idstring— Act on another project

Example

curl -X POST "https://hotmention.com/api/v1/leads/lead_9a1c/skip" \
  -H "Authorization: Bearer hm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"reason": "not a buyer"}'

Response

{ "lead": { "id": "lead_9a1c", "pipelineStage": "SKIPPED", "...": "the lead object" } }

GET/api/v1/budget

The project's Reddit reply budget: caps you set in Settings → Reply (default 3 a day, 10 a week), used and remaining, and the suggested time for the next reply (60-minute spacing).

🔑 Requires Authorization: Bearer hm_your_key

Example

curl "https://hotmention.com/api/v1/budget" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{
  "reddit": {
    "dailyCap": 3,
    "weeklyCap": 10,
    "usedToday": 1,
    "usedWeek": 4,
    "remainingToday": 2,
    "remainingWeek": 6,
    "exhausted": false,
    "lastRepliedAt": "2026-09-11T07:20:00.000Z",
    "nextSuggestedAt": "2026-09-11T08:20:00.000Z"
  },
  "project": { "id": "prj_123", "name": "Warmhound" }
}

GET/api/v1/visibility

The Citation Share scoreboard: cited in N of M checks on the latest complete run, the delta against the previous run, per-engine tiles, and the prompts where competitors are cited instead with the source feeding each answer.

🔑 Requires Authorization: Bearer hm_your_key

Example

curl "https://hotmention.com/api/v1/visibility" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{
  "status": "ready",
  "promptsCount": 30,
  "enginesEnabled": ["chatgpt", "aio", "perplexity", "claude"],
  "latest":   { "runId": "run_77", "trigger": "scheduled", "startedAt": "2026-09-08T04:00:00.000Z", "finishedAt": "2026-09-08T04:19:41.000Z", "checksTotal": 120, "checksCited": 7 },
  "previous": { "runId": "run_71", "trigger": "scheduled", "startedAt": "2026-09-01T04:00:00.000Z", "finishedAt": "2026-09-01T04:18:02.000Z", "checksTotal": 120, "checksCited": 5 },
  "share": 6,
  "deltaCited": 2,
  "deltaSharePoints": 2,
  "engines": [
    { "engine": "chatgpt", "label": "ChatGPT", "checks": 30, "cited": 3 },
    { "engine": "aio", "label": "AI Overviews", "checks": 30, "cited": 1 },
    { "engine": "perplexity", "label": "Perplexity", "checks": 30, "cited": 2 },
    { "engine": "claude", "label": "Claude", "checks": 30, "cited": 1 }
  ],
  "losing": [
    {
      "promptId": "prm_12",
      "text": "best email warmup tool for cold outreach",
      "citedBrands": ["Instantly", "Lemwarm"],
      "topSource": { "url": "https://www.reddit.com/r/Emailmarketing/comments/...", "domain": "reddit.com" },
      "engines": ["ChatGPT", "Perplexity"]
    }
  ],
  "progress": null,
  "nextRunAt": "2026-09-15T04:00:00.000Z",
  "lastRunAt": "2026-09-08T04:19:41.000Z",
  "caption": "Engines answer probabilistically; week-to-week noise of ±1 prompt is normal.",
  "message": "Cited in 7 of 120 checks (6%), +2 vs the previous run."
}

Mentions and keywords

GET/api/v1/mentions

Fetch scored mentions matching your keywords (HOT, WARM and LOW), sorted by intent score.

🔑 Requires Authorization: Bearer hm_your_key

Query Parameters

keywordsstringrequired— Comma-separated keywords to search for

platformstring— Filter by platform: REDDIT, TWITTER, LINKEDIN, QUORA, THREADS, YOUTUBE

score_minnumber— Minimum intent score (default: 40)

limitnumber— Max results to return, 1-100 (default: 20)

sinceISO date— Only mentions after this date (default: 24h ago)

Example

curl "https://hotmention.com/api/v1/mentions?keywords=referral+program,affiliate+software&score_min=50&limit=10" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{
  "mentions": [
    {
      "id": "abc123",
      "platform": "REDDIT",
      "url": "https://reddit.com/r/SaaS/...",
      "title": "Looking for a referral program tool",
      "content": "We need a simple way to set up affiliate tracking...",
      "author": "u/saasfounder",
      "score": 87,
      "scoreLabel": "HOT",
      "shouldReply": true,
      "shouldReplyReason": "Direct product match, high buying intent",
      "draftReply": "Hey! You might want to check out...",
      "competitorsFound": { "found": true, "inPost": ["PartnerStack"], "inReplies": [] },
      "postedAt": "2026-02-16T08:30:00Z",
      "matchedKeyword": "referral program"
    }
  ],
  "total": 42,
  "plan": "GROWTH",
  "limits": { "monthlyLeads": 500, "used": 39 }
}

GET/api/v1/keywords

List all active keywords for your project.

🔑 Requires Authorization: Bearer hm_your_key

Example

curl "https://hotmention.com/api/v1/keywords" \
  -H "Authorization: Bearer hm_your_key_here"

Response

{
  "keywords": [
    { "id": "kw1", "term": "referral program", "createdAt": "2026-01-15T10:00:00Z" },
    { "id": "kw2", "term": "affiliate software", "createdAt": "2026-01-15T10:00:00Z" }
  ],
  "projectName": "My SaaS"
}

POST/api/v1/keywords

Add new keywords to your project. Subject to your plan's keyword limit.

🔑 Requires Authorization: Bearer hm_your_key

Request Body (JSON)

keywordsstring[]required— Array of keyword strings to add

Example

curl -X POST "https://hotmention.com/api/v1/keywords" \
  -H "Authorization: Bearer hm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["CRM alternative", "best CRM for startups"]}'

Response

{ "added": 2 }

POST/api/v1/keys

Create a new API key bound to a project (requires session auth, not API key).

Request Body (JSON)

namestring— Label for the key (default: 'Default')

productIdstring— Project the key acts on (default: your active project)

Example

curl -X POST "https://hotmention.com/api/v1/keys" \
  -H "Cookie: your_session_cookie" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Code", "productId": "prj_123"}'

Response

{
  "id": "key_abc123",
  "key": "hm_a1b2c3d4e5f6...",
  "name": "Claude Code",
  "productId": "prj_123",
  "createdAt": "2026-09-11T10:00:00Z"
}

GET/api/v1/keys

List all your API keys (requires session auth).

Example

curl "https://hotmention.com/api/v1/keys" \
  -H "Cookie: your_session_cookie"

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Claude Code",
      "key": "hm_a1b2...ab34",
      "productId": "prj_123",
      "isActive": true,
      "lastUsedAt": "2026-09-11T09:30:00Z",
      "createdAt": "2026-09-01T10:00:00Z"
    }
  ]
}

Rate Limits & Plan Limits

API access is included on every plan, trial included. Requests are limited to 60 per minute; usage is otherwise bound by the project owner's lead, keyword, prompt and platform limits below.

Plan	Leads/month	Keywords	Buying prompts	Competitors	Platforms
Pro ($99) & trial	500	50	30	5	All 6 platforms
Free (legacy)	10	5	5	2	Reddit, X

Add-on packs raise these numbers: +250 leads/month, +25 keywords or +30 buying prompts for $20/month each.

Error Codes

Errors are JSON: { "error": "...", "code": "..." }, with extra fields where they help (a 409 carries the budget).

401Invalid or missing API key, or more than 60 requests a minute

400invalid — missing or malformed parameters (id, date, platform, instructions)

403forbidden, lead_limit_reached, plan_disabled, quota_exhausted — the owner's plan or limits block the action, or you cannot access that project

404not_found — no such lead in this project, or no project bound to the key

409budget_exhausted — the Reddit reply budget is used up; wait for nextSuggestedAt or pass force

Questions? Contact support@hotmention.com