Rankhog Docs
DocsCLIMCPAPI
API Reference

List Opportunities

List actionable Rankhog opportunities for a paid workspace, including timing, blockers, compact evidence, and linked execution state. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

POST
/agent/v1/opportunities

List actionable Rankhog opportunities for a paid workspace, including timing, blockers, compact evidence, and linked execution state. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Authorization

AuthorizationBearer <token>

Rankhog organization API key sent as Authorization: Bearer rhog_....

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/agent/v1/opportunities" \  -H "Content-Type: application/json" \  -d '{    "managedRedditAccountId": "mra_2x9rnkhdemo",    "organizationId": "org_2x9rnkhdemo",    "websiteId": "site_2x9rnkhdemo",    "includeRecent": true,    "limit": 50  }'
{  "items": [    {      "activity": {        "deadlineAt": null,        "nextStep": "The draft is ready. Nothing goes out until you approve it.",        "nextStepAt": null,        "state": "needs_you",        "waitingOn": null      },      "blocker": null,      "classificationState": null,      "confidenceScore": 91,      "evidence": {        "googlePosition": 1,        "googleQuery": "best customer support for Next.js SaaS"      },      "evidenceSummary": {        "googleQuery": "best customer support for Next.js SaaS",        "googleRank": 1,        "sourceCount": 1      },      "id": "opp_2x9opportunity",      "kind": "reddit_comment",      "linkedAction": {        "blockedReason": null,        "executeAt": null,        "id": "act_2x9planned",        "mode": "needs_approval"      },      "outcome": null,      "nextTransitionAt": "2026-06-17T12:00:00.000Z",      "recommendedAction": "Review and approve this comment draft.",      "source": {        "key": "google-scan:signal_123",        "label": "Google #1"      },      "status": "ready",      "summary": "A relevant Reddit discussion ranks first for this buyer query.",      "target": {        "keyword": "best customer support for Next.js SaaS",        "subreddit": "SaaS",        "url": "https://www.reddit.com/r/SaaS/comments/example/thread/"      },      "timing": {        "dueAt": "2026-06-17T12:00:00.000Z",        "expiresAt": null,        "snoozedUntil": null      },      "title": "Comment on the Reddit result at Google #1",      "timeZone": "Europe/Paris",      "updatedAt": "2026-06-17T12:00:00.000Z"    }  ],  "nextCursor": null}
{  "error": {    "code": "agentic_invalid_input",    "details": {      "issues": [        {          "code": "invalid_type",          "message": "Expected string, received undefined.",          "path": [            "organizationId"          ]        }      ]    },    "message": "Request body did not match the agentic capability schema."  }}

{  "error": {    "code": "agentic_unauthorized",    "message": "Authenticate before using Rankhog agentic capabilities."  }}

{  "error": {    "code": "agentic_paid_plan_required",    "details": {      "managedAccountBillingStatus": "active",      "subscriptionStatus": "past_due"    },    "message": "Rankhog agentic capabilities are available only for active or trialing paid workspaces."  }}

{  "error": {    "code": "agentic_missing_scope",    "details": {      "missingScopes": [        "rankhog:read"      ]    },    "message": "Missing required scope: rankhog:read."  }}

{  "error": {    "code": "agentic_managed_account_not_found",    "message": "Managed Reddit account not found."  }}
{  "error": {    "code": "agentic_internal_error",    "message": "Rankhog could not complete this agentic request."  }}

Update Strategy Inputs POST

Replace shared strategy keywords and watched Radar communities. A community Rankhog has a guide for starts watching immediately; any other is saved but stays inactive until a guide exists for it. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Get Opportunity POST

Return one Rankhog opportunity with public-safe evidence, blocker remediation, timing, outcome, and linked action summary. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.