# Rankhog

> Rankhog grows Reddit visibility for paid workspaces with account-safe strategy, drafting, and Desktop-backed execution. Agents integrate through the REST API, MCP server, or CLI, all backed by one capability registry.

- [OpenAPI document](https://api.rankhog.com/agent/openapi.json): machine-readable definition of every REST operation.
- [MCP server](https://api.rankhog.com/mcp): the same capabilities as OAuth-protected MCP tools.
- [Full docs as one file](https://rankhog.com/llms-full.txt)

## Docs

- [Rankhog Docs](https://rankhog.com/docs.md): Learn how to use Rankhog, connect agent tools, and run Reddit action workflows through API, MCP, and CLI.
- [Errors](https://rankhog.com/docs/api/errors.md): Every agentic error code, its HTTP status, and where it can occur.
- [Open API](https://rankhog.com/docs/api.md): Use the Rankhog public REST API with OpenAPI, scoped auth, idempotency, and safe Reddit workflows.
- [CLI](https://rankhog.com/docs/cli.md): Use the Rankhog CLI for agent-safe scripts, JSON output, and the same public API capabilities.
- [Reddit account protection](https://rankhog.com/docs/docs/account-protection.md): Understand weighted action limits, account-aware risk, and how Rankhog protects each Reddit identity.
- [Discovery and Radar](https://rankhog.com/docs/docs/discovery-and-radar.md): Control Rankhog's independent proactive and reactive lanes and manage every result through Opportunities.
- [Use Rankhog](https://rankhog.com/docs/docs.md): Set up a product, connect Reddit, and work from Discovery, Radar, and conversational opportunities.
- [MCP](https://rankhog.com/docs/mcp.md): Connect Rankhog to MCP clients with OAuth, scopes, and safe Reddit tools.
- [Audit Opportunity Draft](https://rankhog.com/docs/api/reference/audit_opportunity_draft.md): 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.
- [begin opportunity draft edit](https://rankhog.com/docs/api/reference/begin_opportunity_draft_edit.md): 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.
- [Cancel Job](https://rankhog.com/docs/api/reference/cancel_job.md): 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.
- [Cancel Opportunity Execution](https://rankhog.com/docs/api/reference/cancel_opportunity_execution.md): 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.
- [Confirm Opportunity Action](https://rankhog.com/docs/api/reference/confirm_opportunity_action.md): 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.
- [confirm warmup communities](https://rankhog.com/docs/api/reference/confirm_warmup_communities.md): 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.
- [Create Reddit Action](https://rankhog.com/docs/api/reference/create_reddit_action.md): 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.
- [Create Reddit Post Draft](https://rankhog.com/docs/api/reference/create_reddit_post_draft.md): Create a ready manual Reddit post draft after fetching subreddit rules. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [Execute Reddit Action](https://rankhog.com/docs/api/reference/execute_reddit_action.md): 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.
- [find another opportunity post](https://rankhog.com/docs/api/reference/find_another_opportunity_post.md): 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.
- [find warmup comment now](https://rankhog.com/docs/api/reference/find_warmup_comment_now.md): 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 Agentic Actor](https://rankhog.com/docs/api/reference/get_agentic_me.md): Return the authenticated Rankhog agentic actor, source, organization, and granted scopes. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [Get Control Pane Analytics Summary](https://rankhog.com/docs/api/reference/get_control_pane_analytics_summary.md): 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 Credit Balance](https://rankhog.com/docs/api/reference/get_credit_balance.md): 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.
- [get credit purchase link](https://rankhog.com/docs/api/reference/get_credit_purchase_link.md): 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 discovery scan](https://rankhog.com/docs/api/reference/get_discovery_scan.md): 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.
- [get draft profile](https://rankhog.com/docs/api/reference/get_draft_profile.md): 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.
- [Get Job](https://rankhog.com/docs/api/reference/get_job.md): 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.
- [Get Opportunity](https://rankhog.com/docs/api/reference/get_opportunity.md): 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 Opportunity Conversation](https://rankhog.com/docs/api/reference/get_opportunity_conversation.md): 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.
- [Get opportunity evidence](https://rankhog.com/docs/api/reference/get_opportunity_evidence.md): 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 Planned Reddit Action](https://rankhog.com/docs/api/reference/get_planned_reddit_action.md): Return one planned Reddit action from a paid workspace. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [get product answers](https://rankhog.com/docs/api/reference/get_product_answers.md): Read the existing product's positioning, audience, and competitors. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [get product settings](https://rankhog.com/docs/api/reference/get_product_settings.md): Read the product's market, posting language, and copilot/autopilot mode. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [Get Radar Activity](https://rankhog.com/docs/api/reference/get_radar_activity.md): 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 Coverage](https://rankhog.com/docs/api/reference/get_radar_coverage.md): Return current Radar watcher coverage and collector health. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [Get Radar Status](https://rankhog.com/docs/api/reference/get_radar_status.md): 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.
- [Get Reddit Account Protection](https://rankhog.com/docs/api/reference/get_reddit_account_protection.md): 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.
- [Get Reddit Action Execution Status](https://rankhog.com/docs/api/reference/get_reddit_action_execution_status.md): 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.
- [Get Reddit Action History](https://rankhog.com/docs/api/reference/get_reddit_action_history.md): 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 Reddit Browser Status](https://rankhog.com/docs/api/reference/get_reddit_browser_status.md): 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.
- [Get Subreddit Activity](https://rankhog.com/docs/api/reference/get_subreddit_activity.md): 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 Subreddit Rules](https://rankhog.com/docs/api/reference/get_subreddit_rules.md): 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 warmup participation profile](https://rankhog.com/docs/api/reference/get_warmup_participation_profile.md): Read the account's confirmed participation facts and community portfolio. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [Get Warm-up State](https://rankhog.com/docs/api/reference/get_warmup_state.md): 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 workspace setup status](https://rankhog.com/docs/api/reference/get_workspace_setup_status.md): 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 Workspace Strategy](https://rankhog.com/docs/api/reference/get_workspace_strategy.md): Return the current product-owned Discovery and Radar strategy. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [API Reference](https://rankhog.com/docs/api/reference.md): Generated endpoint reference for the Rankhog agentic REST API.
- [List Agentic Workspaces](https://rankhog.com/docs/api/reference/list_agentic_workspaces.md): List paid Rankhog workspaces and identifiers available to the authenticated actor. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [List Credit Ledger](https://rankhog.com/docs/api/reference/list_credit_ledger.md): 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.
- [list discovery scans](https://rankhog.com/docs/api/reference/list_discovery_scans.md): Inspect recent Discovery scan outcomes, including when product billing is inactive. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [List Opportunities](https://rankhog.com/docs/api/reference/list_opportunities.md): 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.
- [List Planned Jobs](https://rankhog.com/docs/api/reference/list_planned_jobs.md): List planned Rankhog jobs for an organization the actor can access. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [list reddit accounts](https://rankhog.com/docs/api/reference/list_reddit_accounts.md): 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.
- [List Reddit Action History](https://rankhog.com/docs/api/reference/list_reddit_action_history.md): 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.
- [Open Reddit URL](https://rankhog.com/docs/api/reference/open_reddit_url.md): 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.
- [Post Opportunity Conversation Message](https://rankhog.com/docs/api/reference/post_opportunity_conversation_message.md): 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.
- [preview warmup communities](https://rankhog.com/docs/api/reference/preview_warmup_communities.md): Evaluate proposed communities against the existing participation profile and community evidence. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
- [recover strategy setup](https://rankhog.com/docs/api/reference/recover_strategy_setup.md): 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.
- [refresh opportunity source](https://rankhog.com/docs/api/reference/refresh_opportunity_source.md): 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.
- [Reschedule Job](https://rankhog.com/docs/api/reference/reschedule_job.md): 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.
- [resolve reddit action verification](https://rankhog.com/docs/api/reference/resolve_reddit_action_verification.md): 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.
- [resolve warmup safety incident](https://rankhog.com/docs/api/reference/resolve_warmup_safety_incident.md): 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.
- [Retry Job](https://rankhog.com/docs/api/reference/retry_job.md): 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.
- [retry opportunity execution](https://rankhog.com/docs/api/reference/retry_opportunity_execution.md): 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.
- [retry opportunity preparation](https://rankhog.com/docs/api/reference/retry_opportunity_preparation.md): 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.
- [Run Discovery Now](https://rankhog.com/docs/api/reference/run_discovery_now.md): 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 opportunity executor](https://rankhog.com/docs/api/reference/set_opportunity_executor.md): 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.
- [set product automation mode](https://rankhog.com/docs/api/reference/set_product_automation_mode.md): 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.
- [Set Radar Enabled](https://rankhog.com/docs/api/reference/set_radar_enabled.md): Enable or disable Radar without changing Discovery. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [Start Conversation](https://rankhog.com/docs/api/reference/start_conversation.md): 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.
- [Start Discovery](https://rankhog.com/docs/api/reference/start_discovery.md): Start Discovery with an optional product direction. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [start warmup](https://rankhog.com/docs/api/reference/start_warmup.md): Start account warm-up using existing credits and safety checks. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [step in opportunity](https://rankhog.com/docs/api/reference/step_in_opportunity.md): 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.
- [Stop Discovery](https://rankhog.com/docs/api/reference/stop_discovery.md): Stop Discovery without changing Radar. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [stop warmup](https://rankhog.com/docs/api/reference/stop_warmup.md): 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.
- [update discovery direction](https://rankhog.com/docs/api/reference/update_discovery_direction.md): Update Discovery direction without restarting the session. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [update draft profile](https://rankhog.com/docs/api/reference/update_draft_profile.md): 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.
- [Update Opportunity Draft](https://rankhog.com/docs/api/reference/update_opportunity_draft.md): 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.
- [update product answers](https://rankhog.com/docs/api/reference/update_product_answers.md): 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.
- [update product market](https://rankhog.com/docs/api/reference/update_product_market.md): Set the country and language used by discovery and drafting. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
- [Update Strategy Inputs](https://rankhog.com/docs/api/reference/update_strategy_inputs.md): 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.
- [update warmup participation profile](https://rankhog.com/docs/api/reference/update_warmup_participation_profile.md): 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.