API Reference

get workspace setup status

Inspect product browser readiness and setup blockers without exposing device credentials or raw browser control. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

get product answers

Read the existing product's positioning, audience, and competitors. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

update product answers

Update existing product answers and rebuild its product context. Does not create or onboard products. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

get product settings

Read the product's market, posting language, and copilot/autopilot mode. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

update product market

Set the country and language used by discovery and drafting. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Change copilot/autopilot mode. Enabling autopilot additionally requires reddit:write:dangerous; existing audit and grace-window protections remain. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

list reddit accounts

List accounts granted to this product and their current eligibility for the requested action type. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

update discovery direction

Update Discovery direction without restarting the session. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

get discovery scan

Read saved Discovery searches, observed result positions and resulting opportunities. Historical scans may contain only partial evidence. Positions are provider placement, not independently verified Google rankings. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

list discovery scans

Inspect recent Discovery scan outcomes, including when product billing is inactive. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

recover strategy setup

Retry failed strategy setup subject to the existing recovery cooldown and credit limits. Does not bypass the cooldown. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

begin opportunity draft edit

Pause pending automatic work before editing the opportunity draft. Read get_opportunity for the current revision. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

refresh opportunity source

Refresh the exact opportunity post and parent comment availability and metrics. Deduplicated and rate limited; never submits a Reddit action. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

find another opportunity post

Replace an unavailable opportunity source and prepare a new draft for review. Preserves old draft history and refuses submitted or uncertain actions. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

retry opportunity preparation

Retry failed opportunity preparation through its existing guarded recovery path. On a draft whose current audit found concerns, this is Redraft with fixes: the drafting chain writes a new version from the audit's feedback and audits it. Fixing Rankhog's own draft is free; redrafting a team-written draft costs a draft regeneration. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

retry opportunity execution

Retry an eligible failed Reddit execution. Uncertain submissions still require verification before any resend. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

step in opportunity

Stop an opportunity's pending autopilot transition so it can be reviewed. Cannot undo an already submitted Reddit action. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

set opportunity executor

Select a granted eligible Reddit account without sending or rewriting the opportunity draft. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

get draft profile

Read the existing writing profile, the chosen Reddit humanizer level, the three built-in levels and the default prompts. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

update draft profile

Update writing settings. humanizerPreset picks a built-in Reddit humanizer level (reddit_maxxing, informal, professional; null returns to informal) and a humanizerPromptOverride wins over it. Omitted fields retain their current values. Changing the review prompt additionally requires growth:safety:write. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

find warmup comment now

Prepare a relevant warm-up comment now within the existing daily budget. Reuses pending work and preserves retry limits, account pacing and autopilot safeguards; preparing does not mean submitted. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

get warmup participation profile

Read the account's confirmed participation facts and community portfolio. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

update warmup participation profile

Replace participation facts. Confirm only facts supplied or verified by the customer; changing the trust checklist additionally requires growth:safety:write. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

preview warmup communities

Evaluate proposed communities against the existing participation profile and community evidence. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

confirm warmup communities

Confirm AskReddit and two distinct communities. Rankhog rechecks eligibility from current evidence; supplied eligibility cannot override it. Does not start warm-up. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

start warmup

Start account warm-up using existing credits and safety checks. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

stop warmup

Stop the account's active warm-up plan through the normal lifecycle. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

resolve warmup safety incident

Acknowledge the exact current safety incident through the existing guarded resolution path. A stale incident id is rejected. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

resolve reddit action verification

Resolve an uncertain submission. Submitted requires an exact permalink that passes account, content, target, and time checks; never blindly resends. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

get credit purchase link

Return a Rankhog billing link for a human to buy credits. Requires a signed-in billing manager at checkout; never charges or changes billing. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get opportunity evidence

Read bounded opportunity product knowledge, source evidence, community rules, or conversation history. Targets are scoped to the opportunity. Uses cached rules and normal thread caching, never forced refresh. Community reads additionally require reddit:rules:read. Continue text with nextOffset; reset offset when following nextBeforeSeq. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Agentic Actor

Return the authenticated Rankhog agentic actor, source, organization, and granted scopes. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

List Agentic Workspaces

List paid Rankhog workspaces and identifiers available to the authenticated actor. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Subreddit Rules

Fetch verified or live Reddit subreddit rules for a paid Rankhog workspace. Cache policy: cached. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Subreddit Activity

Return subreddit activity from the durable Reactive source without bypassing internal collector scheduling. Cache policy: cached. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Reddit Browser Status

Report whether Rankhog Desktop has a ready Reddit browser session for this managed account. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Open Reddit URL

Open an allowed Reddit URL in the paired Rankhog Desktop browser. This never exposes raw browser control. Cache policy: live. Idempotency: required. Auth modes: mcp_oauth, session_bearer.

Get Workspace Strategy

Return the current product-owned Discovery and Radar strategy. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Radar Coverage

Return current Radar watcher coverage and collector health. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Radar Activity

Return measured Radar screening work and durable opportunity results for this product, including measurement coverage and freshness. Cache policy: cached. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Radar Status

Report whether Radar is running for this workspace, what is blocking it, and what it has checked, surfaced and triaged recently. Cache policy: cached. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Start Discovery

Start Discovery with an optional product direction. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Stop Discovery

Stop Discovery without changing Radar. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Run Discovery Now

Run the active Discovery session now, subject to its hourly limit. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Set Radar Enabled

Enable or disable Radar without changing Discovery. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Update Strategy Inputs

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.

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.

Get Opportunity

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.

Get Planned Reddit Action

Return one planned Reddit action from a paid workspace. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Opportunity Conversation

Read one opportunity's conversation timeline: milestones, drafts, questions, and messages. Poll with afterSeq for new items. Every current opportunity has a conversation; preserved legacy history can return a null conversationId when no old thread exists. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Post Opportunity Conversation Message

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.

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.

Create Reddit Post Draft

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

Create Reddit Action

Create a stored Reddit write action for post, comment, reply, upvote, or join_subreddit. Draft approval and write execution remain separate. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Execute Reddit Action

Queue an authorized post, comment, reply, upvote, or join for Desktop execution and return a stable execution ID immediately. Duplicate idempotent triggers reuse the existing execution. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Get Reddit Action Execution Status

Return normalized status for a Reddit action execution, including workflow step, final Reddit permalink, human-needed state, and structured failure or verification-required details. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

List Reddit Action History

List and filter the immutable Reddit action execution ledger, including creation origin and aggregate community support, for one paid Rankhog workspace. `actionTypes` filters by several types at once. Each comment, reply and post carries a body preview, `contentKind` (linked the product's site, named it, on topic, or warm-up), the thread title, the latest observed Reddit numbers, its opportunity, and for Discovery finds the Google position when found. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Reddit Action History

Inspect one tenant-scoped Reddit action receipt with immutable origin, aggregate community support, lifecycle events, observations, and derived performance. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Control Pane Analytics Summary

Return the cached Rankhog control-pane analytics summary for a paid workspace. `recap` covers the period's submitted comments, replies and posts, each labelled by what it did for the product, with upvotes, replies, a per-day grid and a per-account breakdown. `recap.siteVisits` is the visits from Reddit that the customer's own analytics (Plausible, Fathom or Datafast, connected in the app) counted in the last 7 days and the 7 before, or null when none is connected; Rankhog adds no tracking links. The recap needs `reddit:activity:read`; without it `recap` is null. Cache policy: cached. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Job

Return one authorized background job snapshot. API keys can inspect jobs in their organization. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

List Planned Jobs

List planned Rankhog jobs for an organization the actor can access. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Confirm Opportunity Action

Confirm one opportunity's linked Reddit action for execution: approve it, resolve the send schedule, and queue Desktop execution. This is the send step, so API keys need reddit:write:dangerous via the automation preset. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Cancel Opportunity Execution

Cancel one opportunity's pending execution and dismiss the opportunity. Running Reddit writes cannot be stopped mid-flight; their approval is rejected so the preflight aborts. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Update Opportunity Draft

Edit one opportunity's linked Reddit draft. Direct saves immediately; audited mode saves first, then checks the saved revision. Changes retain the requesting actor attribution. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Audit Opportunity Draft

Audit a saved draft revision. Returns advisory findings without editing, approving, scheduling, or executing it. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Get Warm-up State

Return the workspace warm-up snapshot: active plan progress, connection-pause reasons, remaining warming time, today's work, per-account warming state, credit requirement, and account health. Connection pauses resume automatically after repair; the credit's 90-day expiry remains unchanged. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Get Reddit Account Protection

Return the protection policy and pacing risk that gate Reddit writes for one workspace account, so a blocked execution can be predicted instead of discovered. Changing the policy stays human-only. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

Cancel Job

Cancel one scheduled Rankhog job the actor is authorized for. Running, finished, failed, and cancelled jobs cannot be cancelled. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Reschedule Job

Move one scheduled Rankhog job to a new time. Only scheduled jobs can be rescheduled. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Retry Job

Retry one failed Rankhog job as a fresh scheduled run. Only failed jobs can be retried. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.

Get Credit Balance

Return the credit balance for an organization, or for one product when websiteId is set: period credits, organization bank, committed and spendable amounts, per-product balances, and the current cost table. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.

List Credit Ledger

Page through the organization credit ledger, newest first: grants, purchases, refunds, adjustments, and every debit with its actor kind and the action, warm-up, purchase, or opportunity it paid for. Member names and user ids are never included. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.