Rankhog Docs
DocsCLIMCPAPI
API Reference

Start Conversation

Start a conversation from a prompt, like the New composer in Rankhog. A Reddit post or comment link becomes a reply opportunity: Rankhog reads the thread and drafts the reply the prompt asks for. Anything else starts a conversation the agent answers; it can start a post when a community is named. If the thread already has an opportunity, the prompt joins that conversation (outcome existing). Nothing is sent to Reddit until a person confirms. With an organization API key the agent answers but the AI draft waits for a person. Poll get_opportunity_conversation for the reply. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

POST
/agent/v1/conversations

Start a conversation from a prompt, like the New composer in Rankhog. A Reddit post or comment link becomes a reply opportunity: Rankhog reads the thread and drafts the reply the prompt asks for. Anything else starts a conversation the agent answers; it can start a post when a community is named. If the thread already has an opportunity, the prompt joins that conversation (outcome existing). Nothing is sent to Reddit until a person confirms. With an organization API key the agent answers but the AI draft waits for a person. Poll get_opportunity_conversation for the reply. Cache policy: live. Idempotency: required. 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

application/json

application/json

curl -X POST "https://example.com/agent/v1/conversations" \  -H "Content-Type: application/json" \  -d '{    "managedRedditAccountId": "mra_2x9rnkhdemo",    "organizationId": "org_2x9rnkhdemo",    "websiteId": "site_2x9rnkhdemo",    "idempotencyKey": "start-2026-09-30-001",    "prompt": "Reply to this and keep it short: https://www.reddit.com/r/SaaS/comments/1abcde/how_do_you_find_users/"  }'
{  "conversationId": "conv_2x9conversation",  "itemId": "item_2x9prompt",  "kind": "reddit_comment",  "opportunityId": "opp_2x9opportunity",  "outcome": "created"}
{  "error": {    "code": "agentic_invalid_input",    "message": "Write a message first."  }}

{  "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",        "conversation:write"      ]    },    "message": "Missing required scope: rankhog:read, conversation:write."  }}

{  "error": {    "code": "agentic_managed_account_not_found",    "message": "Managed Reddit account not found."  }}

{  "error": {    "code": "agentic_workspace_unavailable",    "message": "This product is not set up for Reddit work yet."  }}

{  "error": {    "code": "agentic_write_rate_limited",    "details": {      "limit": 30,      "windowSeconds": 3600    },    "message": "You can start 30 conversations an hour. Try again in a few minutes."  }}
{  "error": {    "code": "agentic_internal_error",    "message": "Rankhog could not complete this agentic request."  }}

Post Opportunity Conversation Message POST

Steer an opportunity conversation or answer its pending question with the optional answer.questionId, then queue an agent turn. Terminal and cutover-history conversations are read-only. Messages do not grant execution permission; use confirm_opportunity_action with the explicit dangerous-write grant to send. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Create Reddit Post Draft POST

Create a ready manual Reddit post draft after fetching subreddit rules. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.