Open API

Use the Rankhog public REST API with OpenAPI, scoped auth, idempotency, and safe Reddit workflows.

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

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

The OpenAPI 3.1 document is available at:

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

See the generated 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. They can execute Reddit writes only when the key has reddit:write:dangerous and the workspace, account, billing, pacing, approval, and Desktop checks pass.

Capability	API key	CLI/session	OAuth
Read workspaces, rules, strategy, analytics, planned jobs	`rankhog:read`	Yes	`rankhog:read`
Create stored Reddit actions	`reddit:draft:write`	Yes	`reddit:draft:write`
Execute approved Reddit actions	`reddit:write:dangerous`	Yes	`reddit:write:dangerous`
Open desktop browser URLs, approve legacy drafts, read one job	No	Yes	Yes
Legacy `dangerously_submit_reddit_post`	No	No	OAuth only

Quickstart

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

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.

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

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 approved action. The response is immediate and means the execution was queued, not necessarily submitted.

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.",
    "idempotencyKey": "execute-action-2026-06-17-001"
  }'

Queued response:

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

Poll status:

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.

{
  "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.

{
  "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."
  }
}

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:

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, billing, account grants, strategy/action readiness, subreddit rules, pacing, rate limits, URL policy, and Desktop readiness before queueing execution. Public clients send high-level workflow requests only; raw browser control is not exposed.

The legacy dangerously_submit_reddit_post endpoint remains for compatibility. New clients should use create_reddit_action, execute_reddit_action, and get_reddit_action_execution_status.

Errors

Errors use one shape across REST and CLI:

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

Every REST response includes x-rankhog-request-id when handled by the agentic API.

Next: use the CLI for scripts, or MCP for AI clients with OAuth.