Rankhog Docs
DocsCLIMCPAPI
API Reference

Post Opportunity Conversation Message

Post a plain text message into an opportunity conversation and queue an agent turn. API keys are automation actors: their messages can steer and ask, but Reddit-write confirmations stay human-only. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

POST
/agent/v1/opportunities/conversation/messages

Post a plain text message into an opportunity conversation and queue an agent turn. API keys are automation actors: their messages can steer and ask, but Reddit-write confirmations stay human-only. 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

curl -X POST "https://example.com/agent/v1/opportunities/conversation/messages" \  -H "Content-Type: application/json" \  -d '{    "managedRedditAccountId": "mra_2x9rnkhdemo",    "organizationId": "org_2x9rnkhdemo",    "websiteId": "site_2x9rnkhdemo",    "idempotencyKey": "conv-msg-2026-06-17-001",    "message": "Skip the pricing angle and answer the workflow question.",    "opportunityId": "opp_2x9opportunity"  }'
{  "agentTurnQueued": true,  "conversationId": "conv_2x9conversation",  "created": true,  "itemId": "item_2x9posted",  "seq": 3}
{  "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",        "conversation:write"      ]    },    "message": "Missing required OAuth scope: rankhog:read, conversation:write."  }}

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

{  "error": {    "code": "agentic_write_rate_limited",    "details": {      "limit": 30,      "windowSeconds": 3600    },    "message": "Agentic conversation messages are rate-limited for this workspace."  }}
{  "error": {    "code": "agentic_internal_error",    "message": "Rankhog could not complete this agentic request."  }}

Get Opportunity Conversation POST

Read one opportunity's conversation timeline: milestones, drafts, questions, and messages. Poll with afterSeq for new items. An opportunity that resolved itself may have no conversation; the response then carries a null conversationId and an empty items list. Cache policy: live. Idempotency: none. 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.