# Rankhog Docs
Learn how to use Rankhog, connect agent tools, and run Reddit action workflows through API, MCP, and CLI.
Canonical: https://rankhog.com/docs

Rankhog helps teams grow Reddit visibility with strategy, account-safe workflows, and agent-ready execution surfaces.

Use these docs when you want to:

- **Run the product** from onboarding to Discovery, Radar, and Opportunities.
- **Connect MCP** to approved agent workflows.
- **Use the CLI** for scripts and local agent runs.
- **Call the public API** with OpenAPI schemas, idempotent writes, and status polling.

## Start here

1. Read [Docs](/docs/docs) if you are setting up a workspace.
2. Read [MCP](/docs/mcp) if you want an AI client to call Rankhog safely.
3. Read [CLI](/docs/cli) if you are writing scripts or local workflows.
4. Read [API](/docs/api) if you are building an HTTP integration.

## Current surface

```txt
Product app     Finish desktop verification, configure Radar, start Discovery, then work from Opportunities.
MCP             Available for paid workspaces with OAuth, scopes, and Reddit action tools.
CLI             Available for humans and agents with JSON output.
API             Available with OpenAPI, scoped auth, idempotency, and status polling.
```

## What you need

- A Rankhog account.
- A paid or trialing workspace for protected agent surfaces.
- Rankhog Desktop when a workflow needs a live Reddit browser session.
- A managed Reddit account connected to that workspace.

Keep each workspace tied to one managed Reddit account. That keeps strategy, proof, browser state, and safety history clean.


---

# Errors
Every agentic error code, its HTTP status, and where it can occur.
Canonical: https://rankhog.com/docs/api/errors

{/* This file was generated by scripts/generate-openapi-docs.ts. Do not edit it directly. */}

Every error is the same JSON envelope:

```json
{ "error": { "code": "agentic_missing_scope", "message": "Missing required OAuth scope: strategy:write.", "details": { "missingScopes": ["strategy:write"] } } }
```

Rate limited responses (429) also send a `Retry-After` header with the seconds to wait. Every response carries an `x-rankhog-request-id` header; include it when you report a problem.

| Code | Status | Example message | Where |
| --- | --- | --- | --- |
| `agentic_invalid_input` | 400 | Invalid capability input. | every operation |
| `agentic_invalid_api_key` | 401 | The Rankhog API key is invalid, disabled, or expired. | 42 operations |
| `agentic_unauthorized` | 401 | Authentication is required. | every operation |
| `agentic_insufficient_credits` | 402 | Not enough credits: this draft needs 1, and 0 can be spent right now. A billing manager can buy credits from the Rankhog billing page. | confirm_opportunity_action, execute_reddit_action |
| `agentic_paid_plan_required` | 402 | An active paid product is required. | 43 operations |
| `agentic_plan_feature_locked` | 402 | Discovery is not included in your plan. A person with billing access can upgrade the plan in Rankhog. | confirm_opportunity_action, create_reddit_action, create_reddit_post_draft, execute_reddit_action, get_subreddit_activity, open_reddit_url |
| `agentic_api_key_wrong_organization` | 403 | This API key cannot access the requested organization. | 31 operations |
| `agentic_human_actor_required` | 403 | This agentic capability requires a human-authenticated Rankhog user. | get_subreddit_activity, open_reddit_url |
| `agentic_missing_dangerous_scope` | 403 | Direct Reddit execution requires reddit:write:dangerous for API keys and OAuth clients. | confirm_opportunity_action, execute_reddit_action |
| `agentic_missing_scope` | 403 | The required permission has not been granted. | every operation |
| `agentic_not_org_member` | 403 | The authenticated user is not a member of this organization. | 31 operations |
| `agentic_website_access_denied` | 403 | The authenticated user does not have access to this website. | 24 operations |
| `agentic_discovery_scan_not_found` | 404 | Discovery scan not found. | get_discovery_scan |
| `agentic_execution_not_found` | 404 | Reddit action execution not found. | get_reddit_action_execution_status |
| `agentic_job_not_found` | 404 | Job not found. | cancel_job, get_job, reschedule_job, retry_job |
| `agentic_managed_account_not_found` | 404 | Managed Reddit account not found. | 24 operations |
| `agentic_opportunity_not_found` | 404 | Opportunity not found. | cancel_opportunity_execution, confirm_opportunity_action, get_opportunity, get_opportunity_conversation, get_opportunity_evidence, post_opportunity_conversation_message, update_opportunity_draft |
| `agentic_planned_action_not_found` | 404 | Planned Reddit action not found. | execute_reddit_action, get_planned_reddit_action |
| `agentic_reddit_account_not_found` | 404 | Reddit account not found in this workspace. | get_reddit_account_protection |
| `agentic_website_not_found` | 404 | Product not found. | 32 operations |
| `agentic_conversation_read_only` | 409 | This opportunity conversation is read-only history. | post_opportunity_conversation_message |
| `agentic_draft_conflict` | 409 | The draft changed since revision 3. Reload and edit again. | update_opportunity_draft |
| `agentic_idempotency_conflict` | 409 | This idempotency key was already used with different input. | 19 operations |
| `agentic_job_not_cancellable` | 409 | Only scheduled jobs can be cancelled. | cancel_job |
| `agentic_job_not_reschedulable` | 409 | Only scheduled jobs can be rescheduled. | reschedule_job |
| `agentic_job_not_retryable` | 409 | Only failed jobs can be retried. | retry_job |
| `agentic_managed_account_inactive` | 409 | This managed Reddit account must be active before browser-backed agentic tools can run. | confirm_opportunity_action, create_reddit_action, create_reddit_post_draft, execute_reddit_action, get_subreddit_activity, open_reddit_url |
| `agentic_opportunity_conflict` | 409 | This opportunity is already resolved. | confirm_opportunity_action |
| `agentic_reddit_account_not_ready` | 409 | No product-granted Reddit account has a ready matching desktop browser. | execute_reddit_action |
| `agentic_requested_reddit_account_not_ready` | 409 | The requested Reddit account is not product-granted with a ready matching desktop browser. | execute_reddit_action |
| `agentic_strategy_required` | 409 | Create a Rankhog strategy before storing agent-created Reddit drafts. | create_reddit_action, create_reddit_post_draft |
| `agentic_target_claimed` | 409 | This thread already has work in this product, and it could not be opened. | start_conversation |
| `agentic_workspace_unavailable` | 409 | This product is not set up for Reddit work yet. | start_conversation |
| `job_unsafe_external_verification_required` | 409 | Verify the external action through its product workflow before retrying. | retry_job |
| `agentic_draft_unsafe` | 422 | This warm-up draft has not passed the helpfulness and repetition checks. | update_opportunity_draft |
| `agentic_opportunity_action_invalid` | 422 | Research items run on their own. There is nothing to confirm. | confirm_opportunity_action |
| `agentic_reddit_url_not_allowed` | 422 | Agentic browser tools can only open allowed Reddit URLs. | execute_reddit_action, open_reddit_url |
| `agentic_write_rate_limited` | 429 | Growth mutations are limited to 120 per actor and organization per hour. | 29 operations |
| `agentic_internal_error` | 500 | Rankhog could not complete this agentic request. | 42 operations |
| `agentic_action_not_created` | 503 | Agent-created Reddit action could not be stored. | create_reddit_action |
| `agentic_browser_command_failed` | 503 | Could not queue Reddit browser navigation. | open_reddit_url |
| `agentic_draft_not_created` | 503 | Agent-created Reddit draft could not be stored. | create_reddit_post_draft |


---

# Open API
Use the Rankhog public REST API with OpenAPI, scoped auth, idempotency, and safe Reddit workflows.
Canonical: https://rankhog.com/docs/api

Rankhog exposes the same paid agent capabilities through REST, MCP, and the CLI. Use REST when an external service or AI agent needs stable HTTP endpoints, OpenAPI schemas, idempotent writes, and status polling.

## Base URL

```bash
RANKHOG_API_BASE_URL="https://api.rankhog.com"
```

The OpenAPI 3.1 document is available at:

```bash
curl https://api.rankhog.com/agent/openapi.json
```

See the generated [API reference](/docs/api/reference) for every endpoint schema, response, auth mode, and example.

## Authentication

REST supports three auth paths:

- **Organization API key**: send `Authorization: Bearer rhog_...` or `x-api-key`.
- **CLI bearer token**: minted by Better Auth device authorization.
- **OAuth bearer token**: used by MCP and trusted OAuth clients.

API keys are organization automation credentials. Existing **read only**, **read and draft** (default), and **automation** presets retain their permissions. **Growth operations** adds product, strategy, and warm-up configuration to automation. **Growth operations and safety resolutions** additionally permits safety incidents, participation confirmations, and review-prompt changes. Existing keys are never upgraded automatically.

| Capability | Required permission |
| --- | --- |
| Read growth state, diagnostics, jobs, and credit balance | `rankhog:read` |
| Read the credit ledger | `credits:read` |
| Change product answers, market, or automation mode | `product:write` |
| Configure Discovery and Radar | `strategy:write` |
| Configure/stop warm-up | `warmup:write` |
| Start warm-up execution | `warmup:write` and `reddit:write:dangerous` |
| Edit drafts and writing profiles | `reddit:draft:write` |
| Resolve safety incidents or uncertain submissions; change review prompts or participation trust facts | `growth:safety:write`, plus the operation's configuration permission |
| Execute/retry Reddit writes or enable autopilot | `reddit:write:dangerous`, plus the operation's configuration/draft permission |
| Start conversations, post conversation messages and structured question answers | `conversation:write` |
| Cancel, reschedule, or retry jobs | `jobs:write` |
| Buy credits, change billing, delete data, manage team/security, change account protection | Not exposed |

OAuth grants and API keys need the listed scopes. Human session actors retain their existing role checks. `open_reddit_url` remains human-authenticated. [Get credit purchase link](/docs/api/reference/get_credit_purchase_link) returns a Rankhog billing URL where an authorized human completes checkout; it never charges a card.

Mutations require an `idempotencyKey`. Reuse the key only with identical input: retries return the committed result, while different input returns `agentic_idempotency_conflict`. Permissions and product access are checked again before replay. Durable mutations are limited to 120 per actor and organization per hour; operation-specific limits can be lower.

The retired `approve_reddit_draft` and `dangerously_submit_reddit_post` endpoints have been removed. Use `create_reddit_action` followed by `execute_reddit_action`, or `confirm_opportunity_action` for a linked opportunity. `update_opportunity_draft` now also requires an idempotency key. Text posts use the Desktop post workflow after explicit dangerous execution authorization. A stored draft is not proof of a submission. Execution status reports `humanNeeded` when a person must finish or verify a step in Desktop; API keys cannot mark that human step done.

Every error uses one JSON envelope; see the [error catalog](/docs/api/errors) for all codes, statuses, and remediation. Rate limited responses carry a `Retry-After` header.

## Discovery and Radar

Read the current product-owned strategy:

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/strategy" \
  -H "Authorization: Bearer $RANKHOG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_..."
  }'
```

Strategy mutations require `strategy:write`. Organization API keys may receive this explicit grant; human actors must also be organization owners or admins.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/strategy/discovery/start" \
  -H "Authorization: Bearer $RANKHOG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_...",
    "direction": "Find comparison demand",
    "idempotencyKey": "start-discovery-001"
  }'
```

Stopping Discovery uses `/strategy/discovery/stop`; running it now uses
`/strategy/discovery/run`. Radar coverage is
`/strategy/radar/coverage`, Radar control is `/strategy/radar`, and shared
input replacement is `/strategy/inputs`. These endpoints change only the named
lane or inputs.

## Quickstart

List workspaces, create a Reddit action, execute it, then poll status.

```bash
export RANKHOG_API_BASE_URL="https://api.rankhog.com"
export RANKHOG_API_KEY="rhog_..."

curl "$RANKHOG_API_BASE_URL/agent/v1/workspaces" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
```

Use the returned `organization.id`, `website.id`, and `managedRedditAccount.id` in later calls.

Read the workspace's current opportunities before creating or executing work:

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/opportunities" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_...",
    "managedRedditAccountId": "acct_...",
    "includeRecent": false,
    "limit": 50
  }'
```

Opportunity responses preserve `evidence` and may add `evidenceSummary`,
`timeZone`, and `nextTransitionAt`. These read fields never approve or execute
Reddit work.

Create a stored action. Every write needs an idempotency key.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/reddit-actions" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "actionType": "comment",
    "targetUrl": "https://www.reddit.com/r/SaaS/comments/examplepost/example/",
    "body": "We saw better activation after asking for one setup action instead of showing a long checklist.",
    "riskSummary": "Contextual reply with no link and no promotional claim.",
    "idempotencyKey": "action-comment-2026-06-17-001"
  }'
```

Execute the authorized action. The response is immediate and means the execution was queued, not necessarily submitted.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/reddit-actions/execute" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "plannedRedditActionId": "act_...",
    "acknowledgement": "I understand this can publish or change Reddit state from the user's Reddit account.",
    "requestedExecutorRedditAccountId": "ra_...",
    "idempotencyKey": "execute-action-2026-06-17-001"
  }'
```

Omit `requestedExecutorRedditAccountId` to let Rankhog pick the first ready product-granted Reddit account.

Queued response:

```json
{
  "status": "queued",
  "executionId": "job_...",
  "jobId": "job_...",
  "plannedRedditActionId": "act_...",
  "statusUrl": "/agent/v1/reddit-action-executions/status?executionId=job_..."
}
```

Poll status:

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/reddit-action-executions/status" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "executionId": "job_..."
  }'
```

Successful status includes the final Reddit location.

```json
{
  "status": "succeeded",
  "executionId": "job_...",
  "plannedRedditActionId": "act_...",
  "redditAction": {
    "redditActionId": "ra_...",
    "permalink": "https://www.reddit.com/r/SaaS/comments/examplepost/example/examplecomment/",
    "currentUrl": "https://www.reddit.com/r/SaaS/comments/examplepost/example/examplecomment/",
    "submittedAt": "2026-06-17T11:46:08.000Z",
    "subreddit": "SaaS",
    "type": "comment"
  },
  "failure": null
}
```

Failed status includes machine-readable remediation.

```json
{
  "status": "failed",
  "failedStepId": "validate_subreddit_rules",
  "failure": {
    "reasonCode": "rules_unavailable",
    "message": "The subreddit rules could not be verified before execution.",
    "retryable": true,
    "failedStepId": "validate_subreddit_rules",
    "remediation": "Refresh subreddit rules in Rankhog, review the planned action, then execute again with a new idempotency key."
  }
}
```

## Credits

Posts, comments, replies, and warm-ups spend credits. Read what a product can spend before queuing work:

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/credits/balance" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_..."
  }'
```

```json
{
  "organizationId": "org_...",
  "websiteId": "web_...",
  "period": {
    "allotment": 100,
    "remaining": 82,
    "available": 82,
    "periodStart": "2026-06-01T00:00:00.000Z",
    "periodEnd": "2026-07-01T00:00:00.000Z",
    "source": "stripe_subscription"
  },
  "bank": { "available": 130, "balance": 130 },
  "available": 212,
  "committed": 4,
  "spendable": 208,
  "costs": { "warmup": 50, "draft": 1, "warmup_draft": 0, "post": 0, "comment": 0, "reply": 0, "upvote": 0, "draft_regeneration": 1, "managed_proxy": 5 },
  "monthlyAllotmentPerProduct": 100,
  "lowBalanceThreshold": 20,
  "products": [{ "websiteId": "web_...", "displayName": "Example SaaS", "available": 212, "committed": 4, "spendable": 208, "period": { "allotment": 100 } }]
}
```

`period` is this product's monthly credits, `bank` is the organization pool shared by every product, and `spendable` is `available` minus credits `committed` to queued actions. Omit `websiteId` to read the bank alone.

`costs` is the live price table. A draft (`draft`) costs credits when it is saved, whether you asked for it or autopilot wrote it. Sending a post, comment, or reply costs `0`. A rewrite you ask for is charged `draft_regeneration` on every second rewrite, so it averages half a credit.

Page through the ledger with `/agent/v1/credits/ledger` (`credits:read`). Every grant, purchase, refund, adjustment, and debit is one row with its `actorKind` and the action, warm-up, purchase, or opportunity it paid for. Pass the previous `nextCursor` as `cursor`; it is `null` on the last page. Member names and user ids are never included.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/credits/ledger" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_...",
    "limit": 25
  }'
```

Both reads need organization membership only, so they work on lapsed and locked workspaces. `execute_reddit_action` returns `402 agentic_insufficient_credits` with `required`, `available`, and `spendable` when the product cannot spend the action's cost. Buying credit packs, auto top-up, and admin adjustments are billing changes and stay in the Rankhog app.

## Idempotency

All writes require a caller `idempotencyKey`. Rankhog also derives a server-side key from `plannedRedditActionId`.

- Duplicate execute calls for the same planned action return the existing execution.
- Already submitted actions return the existing submitted Reddit action.
- Ambiguous final-submit states return `verification_required`; do not blindly retry.

## Statuses

`get_reddit_action_execution_status` returns one of:

```txt
queued
running
succeeded
failed
blocked
cancelled
verification_required
```

`verification_required` means Reddit may have accepted the final submit, but Rankhog could not prove it. Check Reddit or refresh state before retrying with a new idempotency key.

## Safety

Rankhog validates permissions/scopes before queueing execution. The execution layer then checks billing, account grants, action readiness, pacing, URL policy, Desktop readiness, Reddit account match, challenge pages, idempotency, and final verification. Public clients send high-level workflow requests only; raw browser control is not exposed.

Every execution also respects the selected identity's [Reddit account protection policy](/docs/docs/account-protection). Weighted hourly and daily budgets and minimum spacing can delay or block an action. REST and organization API keys cannot weaken that human-owned policy.

The retired post-submission endpoint has been removed. Use `create_reddit_action`, `execute_reddit_action`, and `get_reddit_action_execution_status`.

## Working the Opportunity Inbox

An agent can now work an opportunity end to end: read it, edit its draft, send it, or cancel it.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/opportunities/confirm" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_...",
    "managedRedditAccountId": "acct_...",
    "opportunityId": "opp_...",
    "when": { "mode": "now" },
    "idempotencyKey": "confirm-opp-001"
  }'
```

Confirm needs the automation preset (`reddit:write:dangerous`). `/opportunities/cancel` cancels pending execution and dismisses the opportunity; `/opportunities/draft` edits the linked draft with `reddit:draft:write` and an idempotency key. Poll the returned `jobId` through `/agent/v1/reddit-action-executions/status`.

### Start a conversation

[Start conversation](/docs/api/reference/start_conversation) opens a new inbox conversation from a prompt, like typing in New. A Reddit post or comment link becomes a reply card: Rankhog reads the thread and prepares it. Any other prompt becomes a conversation with the agent.

```bash
curl "$RANKHOG_API_BASE_URL/agent/v1/conversations" \
  -H "Authorization: Bearer $RANKHOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "organizationId": "org_...",
    "websiteId": "web_...",
    "managedRedditAccountId": "acct_...",
    "prompt": "https://www.reddit.com/r/SaaS/comments/abc123/how_do_you_find_first_users/",
    "idempotencyKey": "start-001"
  }'
```

The response returns `opportunityId`, `conversationId`, the `kind` (`reddit_comment`, `reddit_reply`, or `user_request`) and the `outcome`. `existing` means the thread already had a card, and the prompt was added there. Then read the conversation with `get_opportunity_conversation`.

- Needs `rankhog:read` and `conversation:write`. Limited to 30 starts per actor and product per hour.
- You may pass your own `opportunityId` and `conversationId` (uppercase ULIDs). Sending them again with the same prompt returns the same result; any other use returns `agentic_idempotency_conflict`.
- An API key starts the conversation, but the agent does not write a draft for it: drafts cost credits and need a person on the team. Autopilot never sends a started conversation; confirm it yourself.

## TypeScript SDK

`@rankhog/sdk` is a thin typed client generated from this OpenAPI document:

```ts
import { createIdempotencyKey, createRankhogClient } from "@rankhog/sdk";

const rankhog = createRankhogClient({ apiKey: process.env.RANKHOG_API_KEY! });

const { items } = await rankhog.post("/agent/v1/opportunities", {
  organizationId: "org_...",
  websiteId: "web_...",
  managedRedditAccountId: "acct_...",
});

await rankhog.post("/agent/v1/opportunities/confirm", {
  organizationId: "org_...",
  websiteId: "web_...",
  managedRedditAccountId: "acct_...",
  opportunityId: items[0]!.id,
  idempotencyKey: createIdempotencyKey("confirm"),
});
```

Request bodies and responses are fully typed per path, and failures throw `RankhogApiError` with the error code, request id, and `Retry-After` seconds.

## Errors

Errors use one shape across REST, MCP, and CLI. See the [error catalog](/docs/api/errors) for every code.

```json
{
  "error": {
    "code": "agentic_missing_scope",
    "message": "Missing required scope: reddit:draft:write.",
    "details": {
      "missingScopes": ["reddit:draft:write"]
    }
  }
}
```

Every REST response includes `x-rankhog-request-id` when handled by the agentic API. Rate limited responses (429) include `Retry-After` seconds.

For AI-assisted integration, every docs page is also raw markdown: append `.md` to its URL, or fetch [/llms.txt](/llms.txt) for the index and [/llms-full.txt](/llms-full.txt) for everything in one file.

Next: use the [CLI](/docs/cli) for scripts, or [MCP](/docs/mcp) for AI clients with OAuth.


---

# CLI
Use the Rankhog CLI for agent-safe scripts, JSON output, and the same public API capabilities.
Canonical: https://rankhog.com/docs/cli

The Rankhog CLI calls the public REST API. It is designed for humans and AI agents.

## Configure

```bash
export RANKHOG_API_BASE_URL="https://api.rankhog.com"
export RANKHOG_OUTPUT="json"
```

Agents should prefer `--json` or `RANKHOG_OUTPUT=json`.

## Sign In

The CLI uses Better Auth device authorization.

```bash
rankhog login
```

For non-interactive agents, print the code without polling:

```bash
rankhog --json login --no-poll --no-open
```

You can also provide a bearer token directly:

```bash
export RANKHOG_ACCESS_TOKEN="..."
```

Device tokens are stored in the CLI YAML config with file mode `0600`. `RANKHOG_ACCESS_TOKEN` always takes precedence for ephemeral agent runs.

## Find Workspace IDs

```bash
rankhog --json workspaces list
```

Set defaults for scripts:

```bash
export RANKHOG_ORGANIZATION_ID="org_..."
export RANKHOG_WEBSITE_ID="web_..."
export RANKHOG_MANAGED_REDDIT_ACCOUNT_ID="acct_..."
```

## Common Commands

```bash
rankhog --json reddit rules SaaS
rankhog --json reddit activity SaaS --max-posts 25 --max-comments 25
rankhog --json strategy radar coverage
rankhog --json reddit actions status job_...
rankhog --json browser status
rankhog --json opportunities list
rankhog --json opportunities get opp_...
rankhog --json strategy show
rankhog --json strategy discovery start --direction "Find comparison demand" --idempotency-key start-001
rankhog --json strategy discovery run --idempotency-key run-001
rankhog --json strategy discovery stop --idempotency-key stop-001
rankhog --json strategy radar disable --idempotency-key radar-off-001
rankhog --json analytics summary --period week
rankhog --json jobs planned --organization-id "$RANKHOG_ORGANIZATION_ID"
rankhog --json jobs cancel job_... --organization-id org_... --idempotency-key cancel-001
rankhog --json warmup state
rankhog --json reddit protection
rankhog --json credits balance
rankhog --json credits ledger --limit 50
```

Every public operation is also reachable without a curated command:

```bash
rankhog --json api operations
rankhog --json api list_opportunities --data '{"organizationId":"org_...","websiteId":"web_...","managedRedditAccountId":"acct_..."}'
```

The `api` group is generated from the same capability registry as REST and MCP, so a new capability is callable from the CLI the day it ships.

## Opportunities

List the workspace's actionable opportunities:

```bash
rankhog --json opportunities list --limit 50
```

Include `--no-recent` to omit completed and dismissed results from the previous 14 days. Inspect one opportunity with its public-safe evidence, blocker remediation, timing, and linked action summary:

```bash
rankhog --json opportunities get opp_...
```

Opportunity responses keep the existing `evidence` field and add a compact
`evidenceSummary` when available. New clients may use optional `timeZone` and
`nextTransitionAt` values for scheduling. Treat missing values as `null`; these
read fields do not grant approval or execution permission.

Work an opportunity from the terminal: read its conversation, message the agent, edit the draft, confirm the send, or cancel it.

```bash
rankhog --json opportunities conversation opp_... --after-seq 0
rankhog --json opportunities message opp_... --message "Tighten the first sentence." --idempotency-key msg-001
rankhog --json opportunities draft opp_... --body "Sharper draft body." --expected-revision 2
rankhog --json opportunities confirm opp_... --now --idempotency-key confirm-001
rankhog --json opportunities cancel opp_... --reason "Thread went stale" --idempotency-key cancel-001
```

Opportunity reads require `rankhog:read`. Confirming a send requires `reddit:write:dangerous`; billing and account changes remain human-authenticated product actions.

Start a new conversation from a prompt, like typing in New. A Reddit post or comment link becomes a reply card:

```bash
rankhog --json api start_conversation --data '{"organizationId":"org_...","websiteId":"web_...","managedRedditAccountId":"acct_...","prompt":"https://www.reddit.com/r/SaaS/comments/abc123/how_do_you_find_first_users/","idempotencyKey":"start-001"}'
```

It needs `conversation:write`. See [Start a conversation](/docs/api#start-a-conversation) for the ids you may pass and the limits.

## Radar Coverage

Inspect source freshness, post/comment overlap, backlog, and eligible collector
capacity without triggering an ad hoc Reddit fetch:

```bash
rankhog --json strategy radar coverage
```

The command requires `rankhog:read`. Radar and Discovery controls require a
human CLI-device actor, `strategy:write`, idempotency, and rate limits.

## Credits

Credits pay for drafts and warm-ups. Sending a post, comment, or reply is free. Read the balance for the default product:

```bash
rankhog --json credits balance
```

The response includes this product's `period` credits, the organization `bank`, `committed` credits held by queued actions, `spendable` credits, every product's balance under `products`, and the current `costs` table. Read the organization as a whole with `--org-wide`, or pick a product with `--website-id`:

```bash
rankhog --json credits balance --org-wide
rankhog --json credits balance --website-id web_...
```

Page through the ledger, newest first. Every grant, purchase, refund, adjustment, and debit is one row with its `actorKind` and the action, warm-up, purchase, or opportunity it paid for:

```bash
rankhog --json credits ledger --limit 50
rankhog --json credits ledger --cursor "..." --limit 50
```

Pass `nextCursor` from the previous page as `--cursor`. `nextCursor` is `null` on the last page.

Both commands need only organization membership, so they work on lapsed and locked workspaces. `credits balance` requires `rankhog:read`; `credits ledger` also requires `credits:read`. The ledger never includes member names or user ids. Buying credit packs, auto top-up, and admin adjustments are billing changes and stay in the Rankhog app.

## Reddit Actions

Use `reddit actions` to store, execute, and poll real Reddit writes through Rankhog Desktop. Supported action types are `post`, `comment`, `reply`, `upvote`, and `join_subreddit`.

Create a comment action:

```bash
rankhog --json reddit actions create \
  --type comment \
  --target-url "https://www.reddit.com/r/SaaS/comments/examplepost/example/" \
  --body "We saw better activation after asking users for one setup action instead of showing a long checklist." \
  --risk-summary "Contextual reply with no link and no promotional claim." \
  --idempotency-key "action-comment-2026-06-17-001"
```

Create a post with flair:

```bash
rankhog --json reddit actions create \
  --type post \
  --subreddit SaaS \
  --title "What actually improved your SaaS activation?" \
  --body-file ./reddit-post.md \
  --flair "Discussion" \
  --risk-summary "Discussion prompt, no link, and relevant to SaaS operators." \
  --idempotency-key "action-post-2026-06-17-001"
```

Execute an authorized action. The response means the work is queued.

```bash
rankhog --json reddit actions execute act_... \
  --acknowledge \
  --idempotency-key "execute-action-2026-06-17-001"
```

Queued response:

```json
{
  "status": "queued",
  "executionId": "job_...",
  "jobId": "job_...",
  "plannedRedditActionId": "act_...",
  "statusUrl": "/agent/v1/reddit-action-executions/status?executionId=job_..."
}
```

Poll status:

```bash
rankhog --json reddit actions status job_...
```

Possible statuses:

```txt
queued
running
succeeded
failed
blocked
cancelled
verification_required
```

`verification_required` means Reddit may have accepted the final submit, but Rankhog could not prove it. Do not blindly execute the same planned action again.

Duplicate execute calls with the same planned action and idempotency key return the existing execution instead of posting twice.

When the product cannot spend the action's cost, execute fails with `402 agentic_insufficient_credits` and reports `required`, `available`, and `spendable`. Check [`credits balance`](#credits) first.

Pass `--executor-reddit-account-id ra_...` to request a specific ready, product-granted Reddit account. Omit it to let Rankhog choose.

List every execution receipt for the current workspace:

```bash
rankhog --json reddit actions history \
  --origin warmup \
  --status submitted \
  --type post \
  --limit 50
```

Origins distinguish `warmup`, `strategy`, `opportunity`, `agentic`,
`manual_test`, and unresolved legacy `unknown` work. Execution mode remains a
separate field.

Inspect the immutable lifecycle, visibility history, observations, and derived
performance for one receipt:

```bash
rankhog --json reddit actions inspect ract_...
```

Both commands require configured organization, website, and managed Reddit
account identifiers plus `rankhog:read` and `reddit:activity:read`.

## Drafts

Drafts are still available for manual workflows. Create a draft from stdin:

`draft.json`:

```json
{
  "subreddit": "SaaS",
  "title": "A useful Reddit-safe title",
  "body": "A helpful draft body."
}
```

```bash
cat draft.json | rankhog --json drafts create \
  --input - \
  --idempotency-key "draft-2026-06-17-001"
```

## Agent Behavior

The CLI avoids prompts and spinners in JSON mode. Errors are machine-readable and use stable exit codes:

- `0`: success.
- `1`: command or API failure.
- `3`: authentication is required.

CLI execution respects the selected identity's [Reddit account protection policy](/docs/docs/account-protection). Weighted rolling budgets and minimum spacing can delay or block an action. The CLI cannot raise or remove those human-owned limits.

Next: read the [API](/docs/api) reference for HTTP automation or [MCP](/docs/mcp) for OAuth tool calls.


---

# Reddit account protection
Understand weighted action limits, account-aware risk, and how Rankhog protects each Reddit identity.
Canonical: https://rankhog.com/docs/docs/account-protection

Rankhog applies one protection policy to each Reddit account. The policy follows that identity across every product and organization that can use it.

## Why account protection exists

Reddit identities build trust over time. Sudden, repetitive, or unnatural activity can put that trust at risk, even when each individual action looks harmless.

Protection gives the account owner clear ceilings for visible actions. It does not replace good judgment, subreddit rules, or useful writing.

## Reddit is not a numbers game

Protection points are ceilings, not credits to spend or daily goals to complete.

- One relevant, useful contribution is worth more than a high volume of weak activity.
- Rankhog may recommend or execute nothing when there is no worthwhile opportunity.
- More posts, comments, or karma do not automatically create authority.
- High karma and account age provide context. They are not permission to spam or ignore community rules.

## Why actions have different weights

| Action | Points | Why |
| --- | ---: | --- |
| Post | 4 | A post creates new top-level content and attracts broader moderation attention. |
| Comment or reply | 2 | Quality depends heavily on relevance, context, and writing. |
| Upvote or subreddit join | 1 | These are lower-impact actions, but rapid or unnatural patterns still matter. |
| Read-only research | 0 | Reading and evaluating public context does not change Reddit state. |

The fixed ratio is **4:2:1**. Action quality and community fit still matter more than point cost.

## How rolling budgets work

Balanced protection starts with:

```txt
10 points per rolling 24 hours
6 points per rolling hour
30 minutes between visible actions
```

At 10 daily points, the ceiling is two posts, five comments or replies, ten upvotes or joins, or a mixed combination. For example:

```txt
1 post (4) + 1 comment (2) + 4 upvotes (4) = 10 points
```

The hourly and daily budgets apply together. Two posts use 8 points, so the 6-point hourly default prevents them from happening within the same rolling hour even though they fit under the daily ceiling.

Rankhog includes the pending action before checking a budget. When a limit is reached, it calculates when enough weighted history will leave each rolling window and schedules one recheck at the latest eligibility time. Minimum spacing is evaluated at the same time.

If an enabled budget is lower than an action's cost, that action is not allowed. Rankhog returns `action_not_allowed_by_budget` instead of scheduling a retry that can never succeed.

Each daily, hourly, or spacing limit can be removed independently. Removing a limit increases advisory risk; it does not remove approvals, billing checks, account-health blocks, browser readiness, warm-up rules, or subreddit rules.

## How risk is calculated

The risk score combines configured pace with the latest known account context.

### Pace exposure

- Daily exposure is 0 at 6 points or fewer and 100 at 18 points or more.
- Hourly exposure is 0 at 4 points or fewer and 100 at 12 points or more.
- Spacing exposure is 0 at 45 minutes or more and 100 at 5 minutes or fewer.
- A removed limit has 100 exposure for that setting.

Rankhog combines those inputs as 40% daily, 35% hourly, and 25% spacing. The balanced 10/6/30 defaults have about **31/100 Moderate pace exposure** before account context is added.

### Account vulnerability

Rankhog reuses the account health score, including:

- Effective account age.
- Total and comment karma.
- Known Reddit health.

Age advances from the latest snapshot date. Karma stays at its last observed value. Missing data is handled conservatively, and snapshots older than the normal daily capture interval are marked stale.

The combined score is:

```txt
pace exposure + (100 - pace exposure) × account vulnerability × 0.5
```

Account vulnerability is `100 - account health score`. Strong account history can never reduce the underlying pace exposure.

| Score | Label |
| ---: | --- |
| 0–19 | Low |
| 20–39 | Moderate |
| 40–69 | High |
| 70–100 | Very high |

The score is advisory. It is not a guarantee against Reddit moderation or enforcement.

## How to choose settings

Open the organization settings, find the Reddit account, and select **Protection settings**. The dialog has three tabs: **Limits** for the budgets and spacing, **Activity** for the daily activity switch, and **Risk** for the advisory score and the account context behind it. Only a manager in the account's owner organization can save changes. Organizations with granted access can review the global policy but cannot modify it.

| Approach | Configuration principle | Use it when |
| --- | --- | --- |
| Safer | Lower point ceilings and longer spacing | The account is new, low-karma, recovering, or its health is uncertain. |
| Balanced | Keep the 10/6/30 defaults | You want a moderate starting ceiling while Rankhog remains selective. |
| Aggressive | Raise ceilings or shorten spacing | You understand the added exposure and still want more execution flexibility. |
| Disabled protection | Remove one or more limits | You accept maximum exposure for each removed control. Very high configurations require acknowledgement. |

Do not choose a setting because you want Rankhog to “use” the capacity. Choose the maximum activity the account may safely consider when worthwhile opportunities exist.

## Keep the account active

By default, Rankhog casts a few upvotes a day from each connected account, with some scrolling around the post first, so the account looks like a regular Reddit user rather than one that only shows up to post. The votes go to recent posts in communities the account or other Rankhog users take part in, spread across the day. They use their own small pacing budget and never spend the limits above.

To stop this for an account, open its **Protection settings**, go to the **Activity** tab, and turn **Keep the account active** off. Rankhog then only uses the account for work you approve. Votes already queued for the current day are cancelled with the switch.

While a warm-up runs on the account, the daily upvotes are part of the warm-up and keep running whatever the switch says. Your choice takes effect again when the warm-up ends.

## What protection cannot guarantee

Protection does not override:

- Subreddit rules and moderator decisions.
- Content relevance, quality, or transparency.
- Reddit's platform-wide enforcement systems.
- Human approval and Rankhog's other execution safeguards.

A contribution can still be removed or sanctioned at a low pace. A high limit does not make poor participation safe.

## Agent behavior

REST, MCP, and CLI executions respect the selected Reddit account's protection policy. They can encounter a protection delay or an action blocked by budget, but they cannot raise or remove the limits.

Protection changes remain in the human-authenticated organization settings flow. Organization API keys, OAuth apps, MCP tools, REST clients, and the CLI cannot modify them. The read-only protection capability reports the **Keep the account active** switch as `keepActive`; it cannot change it either.

Next: return to [Use Rankhog](/docs/docs), or review execution safeguards in the [API guide](/docs/api), [MCP guide](/docs/mcp), and [CLI guide](/docs/cli).

## Was this helpful?

[Send documentation feedback](mailto:anthony@cossistant.com?subject=Rankhog%20account%20protection%20docs).


---

# Discovery and Radar
Control Rankhog's independent proactive and reactive lanes and manage every result through Opportunities.
Canonical: https://rankhog.com/docs/docs/discovery-and-radar

Each product has one strategy with two independent lanes.

## Radar

Radar watches your verified communities and shared keywords. It evaluates new
Reddit posts and comments continuously and surfaces timely, relevant work.

- Radar is enabled by default after input setup.
- Disabling it stops new evaluations, not existing conversations or history.
- Radar is independent from Discovery and account warm-up.
- Time-sensitive Radar work does not consume the Discovery daily limit.

New products show **Setting up** while Rankhog derives keywords and candidate
communities from your product context.

### Review Radar finds

Radar checks what a discussion is about against what your product does before
showing it. Ordinary opportunities need a concrete product fit and a score of
at least 50. Keyword overlap, unrelated launches, and already-solved needs are
filtered out.

Genuine product and competitor mentions can appear at lower scores after their
identity is verified in context. Incidental tool names do not qualify. During a
classifier outage, new candidates wait internally. Existing cards keep their
current lifecycle.

The inbox puts other decisions needing you first, then Radar finds by relevance.
Choose **Load more** to reach lower-ranked finds. Copilot drafts a reply when you
ask. Strong autopilot finds can prepare a draft after appearing; a passing audit
and the existing intervention window still precede sending. Drafting failure
leaves the discussion available.

`list_opportunities` returns `nextCursor`. Pass it as `cursor` with the same
workspace and `includeRecent` option to continue. An older mention's
`classificationState: "classification_pending"` means its numeric confidence
is a storage placeholder, not a relevance judgment.

### Shared read capacity

Radar creates watcher demand only for an active paid product or an unexpired
trial with completed setup, verified communities, and an active Reddit account.
When hosted collection is enabled, Rankhog supplies collection capacity and no
desktop contribution is required. Products watching the same community share
its scans. Normal refreshes target five minutes, with faster scans when activity
requires them. A recent scan does not prove complete coverage; Stats shows
freshness and unresolved catch-up separately.

When hosted collection is disabled, an organization must also make one
read-ready Rankhog Desktop available. The
desktop may use a signed-in or anonymous Reddit browser; availability counts
even when Rankhog selects another node. Browser extensions do not count because
they cannot collect Radar activity.

- Before the first contribution, the Radar preference stays enabled but status
  reports `pool_contribution_required`. Open Rankhog Desktop to start
  automatically.
- A desktop seen within seven days keeps normal freshness.
- From day 7 through day 14, exclusive communities use idle capacity with no
  freshness promise.
- At day 14, Rankhog switches Radar off. A returning desktop restores only the
  Radars Rankhog switched off, never one you paused.

If multiple products watch one community, one eligible recent contributor keeps
the shared read at normal priority. Inactive or unpaid products are not
evaluated just because another product caused the read.

### Adding a community

Add up to 30 watched communities and 20 keywords per product, on the Radar tab
or through the API.

A community Rankhog has a guide for starts watching right away. Any other one is
saved to your list but does not become an active watcher yet: Rankhog tells the
team, and it starts watching once its guide is ready. Nothing you add is ever
discarded, and a community that is waiting is shown as waiting rather than
silently doing nothing.

## Discovery

Discovery is proactive and starts only when you ask it to. It runs daily at
09:00 in the organization's timezone.

Discovery:

1. Searches ordinary web results, then Reddit-restricted results for relevant conversations.
2. Verifies Reddit threads through Rankhog's read pool.
3. Extracts a useful pattern without copying the source.
4. Offers a useful comment and, after three days, a competing original post.
5. Audits drafts against current evidence and community rules.

A result includes the actual query and search type. A Reddit-restricted result
means a conversation was found, not that it ranks for the ordinary buyer query.
Search placement does not prove Google traffic or inclusion in an AI answer.
Older threads can qualify for comments when they remain open and relevant.
Confirm reviewed text posts to send them through Rankhog Desktop. If Reddit needs a flair or another manual step, the action shows **Human needed**. Complete the step in Desktop, then choose **Done, continue**; Rankhog checks for an existing submission before resuming.

Discovery rotates through every enabled keyword, checking up to six per scan
and analyzing up to three candidates. Temporary read or audit failures leave
saved finds available for a later scan.

You can edit your direction while Discovery runs. Changes to product context,
market, direction, or enabled keywords prevent older scans from surfacing new
work under the previous inputs. Previously offered or dismissed actions are not
recreated just because the strategy changed.

Manual runs use the same scan path and allow one accepted start per product per
hour. Discovery can surface at most five Reddit-action opportunities per
organization-local product day.

## Reviewing a quiet strategy

After three completed empty daily scans with coverage of every enabled keyword,
Discovery explains what it searched and offers up to three grounded changes.
Manual runs, technical failures, incomplete coverage, and pending work do not
count toward that threshold. If there are no enabled keywords, it asks you to
add a buyer query.

**Discovery keeps scanning.** You receive one review per dry episode through
your strategy-notification preferences. Review keyword or community proposals
in Opportunities. Suggested direction text can be loaded into the direction
editor, where you can edit it before saving. Configuration changes always need
a human, including in autopilot.

## Opportunity conversations

Every opportunity has one Chat SDK conversation and one executable action. A
single search winner may create a separate comment opportunity and original-post
opportunity so each can be revised or dismissed independently.

Opportunities can wait for an eligible Reddit account; sending still requires a
non-warming account that passes the execution checks. If a system-selected account becomes unavailable, Rankhog can reassign
it and records the change in the timeline. A user-selected account is pinned;
Rankhog blocks and asks instead of switching silently.

### Mark an opportunity done

Choose **Mark as done** beside Delete when you have handled an opportunity.
For a Reddit post, comment, or reply, paste its permalink to track the score
and replies, or leave the field empty and add it later. You can also tell the
opportunity's chat, “I posted it at [your Reddit permalink].” Rankhog marks it
done and starts checking that link.

Completed Reddit opportunities offer **Add Reddit link** or **Edit Reddit
link**. You can add or correct the link in chat too. This updates tracking
without restarting the work. If Rankhog is already submitting the action,
wait for that execution to settle before marking it done.

Performance appears above the conversation and under **Manually posted
results** on the Stats page. Checks use public Reddit metrics; views and visits
are not available. A pending or unavailable check is not a zero. Manual results
stay separate from Rankhog submissions, and duplicate links count once.

## Public capabilities

REST, OpenAPI, MCP, and the CLI use the same capability layer:

```txt
get_workspace_strategy
get_radar_status
get_radar_coverage
start_discovery
stop_discovery
run_discovery_now
set_radar_enabled
update_strategy_inputs
```

`get_workspace_strategy` includes Discovery coverage, the current review, and
typed search evidence. Reads require `rankhog:read`. Mutations require `strategy:write`, a human OAuth
or CLI-device actor, an idempotency key, and rate limits. Organization API keys
can read strategy state but cannot mutate it.
Read priority is internal and cannot be changed through REST, MCP, or CLI.

`get_radar_status` can return the warning code `results_delayed` while its state
remains `live`. This means Radar accepted one or more results but their cards
are still being retried. The warning clears automatically after the last
affected result surfaces, is rejected, or expires.

Its `activity` covers the last 14 days. `activity.days` lists one entry per
day in your organization's time zone, oldest first, with the conversations
Radar checked and the cards it surfaced that day. The totals are sums over
those days; `waitingCount` counts every open card whatever its age.

`update_strategy_inputs` replaces the whole list. Communities Rankhog has a guide
for come back `verified`; the rest come back `pending` and start watching once
their guide ships. Read `verificationStatus` on each subreddit in the response to
tell them apart.

### CLI examples

```bash
rankhog --json strategy show
rankhog --json strategy radar coverage
rankhog --json strategy discovery start \
  --direction "Find comparison demand" \
  --idempotency-key "start-discovery-001"
rankhog --json strategy discovery run \
  --idempotency-key "run-discovery-001"
rankhog --json strategy discovery stop \
  --idempotency-key "stop-discovery-001"
rankhog --json strategy radar disable \
  --idempotency-key "radar-off-001"
rankhog --json strategy inputs \
  --keywords "Intercom alternative" "support software" \
  --subreddits SaaS CustomerSuccess \
  --idempotency-key "strategy-inputs-001"
```

Set `RANKHOG_ORGANIZATION_ID` and `RANKHOG_WEBSITE_ID`, or pass the matching
flags to each command.

Next: review [Reddit account protection](/docs/docs/account-protection) or use
the generated [API reference](/docs/api/reference).

Legacy unclassified mentions return `confidenceScore: null` and
`classificationState: "classification_pending"` through the public API. Their
storage placeholder is never a relevance score.


## Radar activity

Radar shows the work it does for your product over the last 14 days:

- **Posts and comments screened:** screening passes, including items that did
  not match and genuine rechecks after targeting changes. Retries do not count.
- **Opportunities found:** relevant discussions brought to your inbox. The total
  covers the last 14 days. **Today** opens Radar opportunities found on the
  current reporting day, including completed and dismissed cards. Remove the
  filter at the top of the list to see other opportunities. Deleting
  a card does not erase the work from this total.
- **Opportunities handled:** cards completed or dismissed, counted once.
  Expired cards do not count as handled.

The chart uses your workspace timezone and shows when the snapshot was updated.
Days before screening measurement began are marked unavailable. Older opportunity
history may be incomplete; the page labels it. Statistics refresh as work commits,
with short caching, and retain a clearly marked saved snapshot if refresh fails.

Agents can read the same measurements with
[`get_radar_activity`](/docs/api/reference/get_radar_activity).


---

# Use Rankhog
Set up a product, connect Reddit, and work from Discovery, Radar, and conversational opportunities.
Canonical: https://rankhog.com/docs/docs

Rankhog finds useful Reddit opportunities, prepares safe work, and keeps the
decision in one conversation.

## Product flow

```txt
Sign up -> Complete onboarding -> Start trial -> Pair Desktop -> Configure Radar -> Start Discovery -> Work from Opportunities
```

## 1. Complete onboarding

Provide the product, audience, competitors, and search language Rankhog needs to
understand the workspace. Rankhog preserves that context and uses it to build
fresh strategy inputs.

## 2. Pair Rankhog Desktop

Rankhog Desktop performs Reddit reads and writes through an isolated browser.
Before visible work can run, connect a Reddit account, verify its identity, and
capture a fresh health snapshot.

Every connected identity follows a global [Reddit account protection
policy](/docs/docs/account-protection).

## 3. Use Radar and Discovery

Radar and Discovery are independent:

- **Radar** watches configured communities and keywords for timely Reddit
  conversations. It is enabled by default after setup.
- **Discovery** researches Reddit pages that already win in search and turns
  reusable patterns into tested opportunities. You decide when it runs.

Stopping Discovery does not stop Radar. Disabling Radar does not stop Discovery.
Warm-up does not pause either lane; warming accounts are simply unavailable for
product writes.

Read [Discovery and Radar](/docs/docs/discovery-and-radar) for controls, limits,
and public API examples.

## 4. Work from Opportunities

Every surfaced opportunity is actionable and has its own conversation. Use the
conversation to:

- Ask why Rankhog found it.
- Revise a draft.
- Choose an eligible Reddit account.
- Confirm, dismiss, snooze, or cancel the work.
- Negotiate and confirm a proposed keyword, community, competitor, or Discovery
  direction.

Configuration changes always need human confirmation. Reddit writes follow the
product's copilot or autopilot setting.

## 5. Review proof

Only submitted Reddit actions count as posts, comments, or replies. Rankhog
keeps receipts, visibility checks, observations, and conversation history so
you can see what happened without treating drafts as completed work.

Next: configure [Discovery and Radar](/docs/docs/discovery-and-radar), then
connect agent workflows with [MCP](/docs/mcp).


---

# MCP
Connect Rankhog to MCP clients with OAuth, scopes, and safe Reddit tools.
Canonical: https://rankhog.com/docs/mcp

Rankhog exposes its growth workflows through MCP. Growth execution requires an active or trialing product; authorized setup diagnostics and credit reads remain available when billing is inactive.

Use MCP when an AI client supports OAuth or bearer API keys and should call named tools instead of raw REST endpoints. The same capability registry backs MCP, REST, and the CLI.

## Endpoint

```txt
https://api.rankhog.com/mcp
```

For local development, use your local API origin:

```txt
http://localhost:48738/mcp
```

## OAuth discovery

```bash
curl https://api.rankhog.com/.well-known/oauth-authorization-server
curl https://api.rankhog.com/.well-known/oauth-protected-resource/mcp
```

## Install in your client

**Claude Code**

```bash
claude mcp add --transport http rankhog https://api.rankhog.com/mcp
```

**Claude (web and desktop)**: Settings, then Connectors, then Add custom connector. Paste `https://api.rankhog.com/mcp`.

**Cursor**: add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rankhog": {
      "url": "https://api.rankhog.com/mcp"
    }
  }
}
```

**VS Code**

```bash
code --add-mcp '{"name":"rankhog","type":"http","url":"https://api.rankhog.com/mcp"}'
```

Any other MCP client that supports streamable HTTP and OAuth works with the same URL. Your client redirects through Rankhog sign-in and OAuth consent.

## Growth workflows

MCP, REST, and CLI use the same capability registry and product services. The [API reference](/docs/api/reference) lists every tool's exact inputs, outputs, and permissions.

| Task | Tools |
| --- | --- |
| Find your product and accounts | `list_agentic_workspaces`, `list_reddit_accounts` |
| Configure positioning and language | `get_product_answers`, `update_product_answers`, `get_product_settings`, `update_product_market` |
| Run Discovery and Radar | Existing strategy tools, `update_discovery_direction`, `list_discovery_scans`, `recover_strategy_setup` |
| Review and work an opportunity | Existing opportunity/conversation tools, `begin_opportunity_draft_edit`, `set_opportunity_executor`, `step_in_opportunity` |
| Start work from a prompt or a Reddit link | `start_conversation` |
| Recover failed work | `retry_opportunity_preparation`, `retry_opportunity_execution`, `get_job`, `get_workspace_setup_status` |
| Set writing preferences | `get_draft_profile`, `update_draft_profile` |
| Manage warm-up | Participation profile and community tools, `start_warmup`, `stop_warmup`, `get_warmup_state` |
| Resolve an incident | `resolve_warmup_safety_incident`, `resolve_reddit_action_verification` |
| Control autopilot | `set_product_automation_mode` |
| Inspect results and credits | Existing history, analytics, and credit tools; `get_credit_purchase_link` |

`post_opportunity_conversation_message` accepts an optional `answer` containing the pending `questionId` and optional `skipped` flag. Send the answer text in `message`. A typed answer cannot consume a different pending question.

## Agent recipe

List opportunities first. If one links to an approved action, execute it with idempotency, then poll status.

```json
{
  "tool": "list_agentic_workspaces",
  "arguments": {}
}
```

```json
{
  "tool": "list_opportunities",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_...",
    "managedRedditAccountId": "acct_...",
    "includeRecent": false,
    "limit": 50
  }
}
```

```json
{
  "tool": "create_reddit_action",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "actionType": "comment",
    "targetUrl": "https://www.reddit.com/r/SaaS/comments/examplepost/example/",
    "body": "We saw better activation after asking users for one setup action instead of showing a long checklist.",
    "riskSummary": "Contextual reply with no link and no promotional claim.",
    "idempotencyKey": "action-comment-2026-06-17-001"
  }
}
```

```json
{
  "tool": "execute_reddit_action",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "plannedRedditActionId": "act_...",
    "acknowledgement": "I understand this can publish or change Reddit state from the user's Reddit account.",
    "idempotencyKey": "execute-action-2026-06-17-001"
  }
}
```

The execute response is immediate:

```json
{
  "status": "queued",
  "executionId": "job_...",
  "jobId": "job_...",
  "plannedRedditActionId": "act_...",
  "statusUrl": "/agent/v1/reddit-action-executions/status?executionId=job_..."
}
```

Poll until terminal:

```json
{
  "tool": "get_reddit_action_execution_status",
  "arguments": {
    "organizationId": "org_...",
    "managedRedditAccountId": "acct_...",
    "executionId": "job_..."
  }
}
```

Terminal statuses are `succeeded`, `failed`, `blocked`, `cancelled`, and `verification_required`.

If status is `verification_required`, do not call `execute_reddit_action` again automatically. Reddit may already have accepted the write.

## Credits

Posts, comments, replies, and warm-ups spend credits. Check what a product can spend before queuing work:

```json
{
  "tool": "get_credit_balance",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_..."
  }
}
```

The response includes `period` (this product's monthly credits), `bank` (organization credits shared by every product), `committed` (held by queued actions), `spendable`, `products`, and `costs`. Omit `websiteId` to read the organization bank alone.

Page through the ledger with `list_credit_ledger`. Pass the previous `nextCursor` as `cursor`; it is `null` on the last page.

```json
{
  "tool": "list_credit_ledger",
  "arguments": {
    "organizationId": "org_...",
    "websiteId": "web_...",
    "limit": 25
  }
}
```

`execute_reddit_action` fails with `402 agentic_insufficient_credits` when the product cannot spend the action's cost. Buying credit packs, auto top-up, and admin adjustments are billing changes and are not MCP tools.

## Scopes

Request the smallest set of scopes your client needs.

```txt
rankhog:read
product:write
strategy:write
warmup:write
growth:safety:write
reddit:rules:read
reddit:activity:read
browser:read
credits:read
conversation:write
reddit:draft:write
reddit:write:dangerous
```

## Permissions and limits

Use an OAuth grant or an organization API key with the required [permissions](/docs/api). Existing keys do not gain growth settings or safety permissions automatically. Bearer API keys work for clients that support custom authorization headers; OAuth discovery remains available for interactive clients.

Normal growth actions consume existing credits. Agents cannot buy credits, change billing or auto top-up, delete data, manage team/security settings, or change account-protection limits. `get_credit_purchase_link` lets a human complete checkout in Rankhog.

All mutations require an idempotency key. Repeating the same request returns its committed result; changing the input requires a new key. Poll returned job/execution ids for completion and use `afterSeq` for conversation updates. An uncertain submission must be verified before another send.

Safety scopes permit explicit incident resolution and review-prompt changes, but retain the existing evidence checks, revision checks, account grants, and execution fences. Enabling autopilot or starting warm-up additionally needs `reddit:write:dangerous`. Browser-backed operations use the customer's approved Rankhog transport; raw browser control is not exposed.

The retired approval and dangerous-post endpoints are removed. See the [migration notes](/docs/api) and the [CLI](/docs/cli) for scripts.


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/audit_opportunity_draft

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `audit_opportunity_draft`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/begin_opportunity_draft_edit

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `begin_opportunity_draft_edit`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/cancel_job

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `cancel_job`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/cancel_opportunity_execution

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `cancel_opportunity_execution`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/confirm_opportunity_action

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `confirm_opportunity_action`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/confirm_warmup_communities

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `confirm_warmup_communities`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/create_reddit_action

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `create_reddit_action`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/create_reddit_post_draft

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `create_reddit_post_draft`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/execute_reddit_action

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `execute_reddit_action`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/find_another_opportunity_post

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `find_another_opportunity_post`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/find_warmup_comment_now

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `find_warmup_comment_now`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_agentic_me

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_agentic_me`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_control_pane_analytics_summary

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_control_pane_analytics_summary`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_credit_balance

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_credit_balance`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_credit_purchase_link

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_credit_purchase_link`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_discovery_scan

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_discovery_scan`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_draft_profile

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_draft_profile`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_job

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_job`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_opportunity

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_opportunity`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_opportunity_conversation

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_opportunity_conversation`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_opportunity_evidence

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_opportunity_evidence`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_planned_reddit_action

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_planned_reddit_action`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_product_answers

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_product_answers`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_product_settings

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_product_settings`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_radar_activity

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_radar_activity`).


---

# Get Radar Coverage
Return current Radar watcher coverage and collector health. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer.
Canonical: https://rankhog.com/docs/api/reference/get_radar_coverage

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_radar_coverage`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_radar_status

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_radar_status`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_reddit_account_protection

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_reddit_account_protection`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_reddit_action_execution_status

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_reddit_action_execution_status`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_reddit_action_history

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_reddit_action_history`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_reddit_browser_status

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_reddit_browser_status`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_subreddit_activity

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_subreddit_activity`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_subreddit_rules

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_subreddit_rules`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_warmup_participation_profile

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_warmup_participation_profile`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_warmup_state

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_warmup_state`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_workspace_setup_status

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_workspace_setup_status`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/get_workspace_strategy

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `get_workspace_strategy`).


---

# API Reference
Generated endpoint reference for the Rankhog agentic REST API.
Canonical: https://rankhog.com/docs/api/reference

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<Cards>
<Card href="/docs/api/reference/get_workspace_setup_status" title="get workspace setup status" description="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." />
<Card href="/docs/api/reference/get_product_answers" title="get product answers" description="Read the existing product's positioning, audience, and competitors. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/update_product_answers" title="update product answers" description="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." />
<Card href="/docs/api/reference/get_product_settings" title="get product settings" description="Read the product's market, posting language, and copilot/autopilot mode. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/update_product_market" title="update product market" description="Set the country and language used by discovery and drafting. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/set_product_automation_mode" title="set product automation mode" description="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." />
<Card href="/docs/api/reference/list_reddit_accounts" title="list reddit accounts" description="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." />
<Card href="/docs/api/reference/update_discovery_direction" title="update discovery direction" description="Update Discovery direction without restarting the session. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/get_discovery_scan" title="get discovery scan" description="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." />
<Card href="/docs/api/reference/list_discovery_scans" title="list discovery scans" description="Inspect recent Discovery scan outcomes, including when product billing is inactive. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/recover_strategy_setup" title="recover strategy setup" description="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." />
<Card href="/docs/api/reference/begin_opportunity_draft_edit" title="begin opportunity draft edit" description="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." />
<Card href="/docs/api/reference/refresh_opportunity_source" title="refresh opportunity source" description="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." />
<Card href="/docs/api/reference/find_another_opportunity_post" title="find another opportunity post" description="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." />
<Card href="/docs/api/reference/retry_opportunity_preparation" title="retry opportunity preparation" description="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." />
<Card href="/docs/api/reference/retry_opportunity_execution" title="retry opportunity execution" description="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." />
<Card href="/docs/api/reference/step_in_opportunity" title="step in opportunity" description="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." />
<Card href="/docs/api/reference/set_opportunity_executor" title="set opportunity executor" description="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." />
<Card href="/docs/api/reference/get_draft_profile" title="get draft profile" description="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." />
<Card href="/docs/api/reference/update_draft_profile" title="update draft profile" description="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." />
<Card href="/docs/api/reference/find_warmup_comment_now" title="find warmup comment now" description="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." />
<Card href="/docs/api/reference/get_warmup_participation_profile" title="get warmup participation profile" description="Read the account's confirmed participation facts and community portfolio. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/update_warmup_participation_profile" title="update warmup participation profile" description="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." />
<Card href="/docs/api/reference/preview_warmup_communities" title="preview warmup communities" description="Evaluate proposed communities against the existing participation profile and community evidence. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/confirm_warmup_communities" title="confirm warmup communities" description="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." />
<Card href="/docs/api/reference/start_warmup" title="start warmup" description="Start account warm-up using existing credits and safety checks. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/stop_warmup" title="stop warmup" description="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." />
<Card href="/docs/api/reference/resolve_warmup_safety_incident" title="resolve warmup safety incident" description="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." />
<Card href="/docs/api/reference/resolve_reddit_action_verification" title="resolve reddit action verification" description="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." />
<Card href="/docs/api/reference/get_credit_purchase_link" title="get credit purchase link" description="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." />
<Card href="/docs/api/reference/get_opportunity_evidence" title="Get opportunity evidence" description="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." />
<Card href="/docs/api/reference/get_agentic_me" title="Get Agentic Actor" description="Return the authenticated Rankhog agentic actor, source, organization, and granted scopes. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/list_agentic_workspaces" title="List Agentic Workspaces" description="List paid Rankhog workspaces and identifiers available to the authenticated actor. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/get_subreddit_rules" title="Get Subreddit Rules" description="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." />
<Card href="/docs/api/reference/get_subreddit_activity" title="Get Subreddit Activity" description="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." />
<Card href="/docs/api/reference/get_reddit_browser_status" title="Get Reddit Browser Status" description="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." />
<Card href="/docs/api/reference/open_reddit_url" title="Open Reddit URL" description="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." />
<Card href="/docs/api/reference/get_workspace_strategy" title="Get Workspace Strategy" description="Return the current product-owned Discovery and Radar strategy. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/get_radar_coverage" title="Get Radar Coverage" description="Return current Radar watcher coverage and collector health. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/get_radar_activity" title="Get Radar Activity" description="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." />
<Card href="/docs/api/reference/get_radar_status" title="Get Radar Status" description="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." />
<Card href="/docs/api/reference/start_discovery" title="Start Discovery" description="Start Discovery with an optional product direction. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/stop_discovery" title="Stop Discovery" description="Stop Discovery without changing Radar. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/run_discovery_now" title="Run Discovery Now" description="Run the active Discovery session now, subject to its hourly limit. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/set_radar_enabled" title="Set Radar Enabled" description="Enable or disable Radar without changing Discovery. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/update_strategy_inputs" title="Update Strategy Inputs" description="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." />
<Card href="/docs/api/reference/list_opportunities" title="List Opportunities" description="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." />
<Card href="/docs/api/reference/get_opportunity" title="Get Opportunity" description="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." />
<Card href="/docs/api/reference/get_planned_reddit_action" title="Get Planned Reddit Action" description="Return one planned Reddit action from a paid workspace. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/get_opportunity_conversation" title="Get Opportunity Conversation" description="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." />
<Card href="/docs/api/reference/post_opportunity_conversation_message" title="Post Opportunity Conversation Message" description="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." />
<Card href="/docs/api/reference/start_conversation" title="Start Conversation" description="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." />
<Card href="/docs/api/reference/create_reddit_post_draft" title="Create Reddit Post Draft" description="Create a ready manual Reddit post draft after fetching subreddit rules. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/create_reddit_action" title="Create Reddit Action" description="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." />
<Card href="/docs/api/reference/execute_reddit_action" title="Execute Reddit Action" description="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." />
<Card href="/docs/api/reference/get_reddit_action_execution_status" title="Get Reddit Action Execution Status" description="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." />
<Card href="/docs/api/reference/list_reddit_action_history" title="List Reddit Action History" description="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." />
<Card href="/docs/api/reference/get_reddit_action_history" title="Get Reddit Action History" description="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." />
<Card href="/docs/api/reference/get_control_pane_analytics_summary" title="Get Control Pane Analytics Summary" description="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." />
<Card href="/docs/api/reference/get_job" title="Get Job" description="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." />
<Card href="/docs/api/reference/list_planned_jobs" title="List Planned Jobs" description="List planned Rankhog jobs for an organization the actor can access. Cache policy: live. Idempotency: none. Auth modes: api_key, mcp_oauth, session_bearer." />
<Card href="/docs/api/reference/confirm_opportunity_action" title="Confirm Opportunity Action" description="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." />
<Card href="/docs/api/reference/cancel_opportunity_execution" title="Cancel Opportunity Execution" description="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." />
<Card href="/docs/api/reference/update_opportunity_draft" title="Update Opportunity Draft" description="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." />
<Card href="/docs/api/reference/audit_opportunity_draft" title="Audit Opportunity Draft" description="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." />
<Card href="/docs/api/reference/get_warmup_state" title="Get Warm-up State" description="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." />
<Card href="/docs/api/reference/get_reddit_account_protection" title="Get Reddit Account Protection" description="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." />
<Card href="/docs/api/reference/cancel_job" title="Cancel Job" description="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." />
<Card href="/docs/api/reference/reschedule_job" title="Reschedule Job" description="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." />
<Card href="/docs/api/reference/retry_job" title="Retry Job" description="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." />
<Card href="/docs/api/reference/get_credit_balance" title="Get Credit Balance" description="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." />
<Card href="/docs/api/reference/list_credit_ledger" title="List Credit Ledger" description="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." />
</Cards>


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_agentic_workspaces

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_agentic_workspaces`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_credit_ledger

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_credit_ledger`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_discovery_scans

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_discovery_scans`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_opportunities

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_opportunities`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_planned_jobs

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_planned_jobs`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_reddit_accounts

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_reddit_accounts`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/list_reddit_action_history

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `list_reddit_action_history`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/open_reddit_url

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `open_reddit_url`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/post_opportunity_conversation_message

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `post_opportunity_conversation_message`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/preview_warmup_communities

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `preview_warmup_communities`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/recover_strategy_setup

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `recover_strategy_setup`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/refresh_opportunity_source

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `refresh_opportunity_source`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/reschedule_job

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `reschedule_job`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/resolve_reddit_action_verification

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `resolve_reddit_action_verification`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/resolve_warmup_safety_incident

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `resolve_warmup_safety_incident`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/retry_job

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `retry_job`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/retry_opportunity_execution

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `retry_opportunity_execution`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/retry_opportunity_preparation

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `retry_opportunity_preparation`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/run_discovery_now

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `run_discovery_now`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/set_opportunity_executor

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `set_opportunity_executor`).


---

# set product automation mode
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.
Canonical: https://rankhog.com/docs/api/reference/set_product_automation_mode

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `set_product_automation_mode`).


---

# Set Radar Enabled
Enable or disable Radar without changing Discovery. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
Canonical: https://rankhog.com/docs/api/reference/set_radar_enabled

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `set_radar_enabled`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/start_conversation

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `start_conversation`).


---

# Start Discovery
Start Discovery with an optional product direction. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
Canonical: https://rankhog.com/docs/api/reference/start_discovery

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `start_discovery`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/start_warmup

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `start_warmup`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/step_in_opportunity

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `step_in_opportunity`).


---

# Stop Discovery
Stop Discovery without changing Radar. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
Canonical: https://rankhog.com/docs/api/reference/stop_discovery

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `stop_discovery`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/stop_warmup

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `stop_warmup`).


---

# update discovery direction
Update Discovery direction without restarting the session. Cache policy: live. Idempotency: required. Auth modes: api_key, mcp_oauth, session_bearer.
Canonical: https://rankhog.com/docs/api/reference/update_discovery_direction

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_discovery_direction`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_draft_profile

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_draft_profile`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_opportunity_draft

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_opportunity_draft`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_product_answers

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_product_answers`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_product_market

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_product_market`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_strategy_inputs

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_strategy_inputs`).


---

# 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.
Canonical: https://rankhog.com/docs/api/reference/update_warmup_participation_profile

This is a generated endpoint reference. The full machine-readable definition lives in the OpenAPI document: https://api.rankhog.com/agent/openapi.json (operation `update_warmup_participation_profile`).