Developers

Authentication

Create an API key in Settings → API keys (Growth and Scale plans). Keys start with cs_live_, are shown once, and are sent as a bearer token:

Authorization: Bearer cs_live_…

Requests act on your first project. Limits: 120 requests/minute per account (60/minute for draft generation). Drafts count against your monthly AI-draft allowance.

REST API

List opportunities

GET /api/v1/opportunities?status=NEW&limit=50 — newest first, up to 100.status is one of NEW, SAVED, DRAFTED, POSTED, DISMISSED.

curl https://commentsurge.vercel.app/api/v1/opportunities?status=NEW \
  -H "Authorization: Bearer $CS_KEY"

{
  "data": [{
    "id": "…", "subreddit": "SaaS", "title": "…", "body": "…", "author": "…",
    "permalink": "https://www.reddit.com/r/…", "postScore": 12, "numComments": 8,
    "intentScore": 8.5, "intentLabel": "HIGH", "intentReasons": ["…"],
    "serpPotential": 6, "status": "NEW", "discoveredAt": "…", "postedReplies": []
  }]
}

Generate a reply draft

POST /api/v1/opportunities/:id/draft with an optional tone (HELPFUL, FRIENDLY, PROFESSIONAL). Every draft is screened by the compliance checker; flags come back with it. Returns 402 when your monthly allowance is used up.

curl -X POST https://commentsurge.vercel.app/api/v1/opportunities/OPP_ID/draft \
  -H "Authorization: Bearer $CS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tone":"HELPFUL"}'

List posted replies

GET /api/v1/replies — your last 100 posted comments with their latest score and removal status.

Errors

• 401 — missing or invalid key, or the account is on the free plan
• 402 — monthly draft allowance used up
• 404 — opportunity not found (or not yours)
• 429 — rate limit exceeded

MCP server

CommentSurge speaks the Model Context Protocol over Streamable HTTP (JSON responses) at https://commentsurge.vercel.app/api/mcp. Point any MCP client that supports remote HTTP servers at it with your API key as a bearer token:

{
  "mcpServers": {
    "commentsurge": {
      "type": "http",
      "url": "https://commentsurge.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer cs_live_…" }
    }
  }
}

Tools:

• list_opportunities — scored opportunities (status, limit)
• generate_draft — AI reply draft for an opportunity (opportunity_id, tone)
• list_dm_prospects — DM pipeline (status)
• get_visibility_scores — latest AI-visibility score per engine

Nothing in the API posts to Reddit. Posting always happens from the app, from your own connected account, after you approve it.