API reference

Getting started with the RedReplier API

The RedReplier API lets external tools, automations, and AI agents manage mention monitoring across Reddit, Hacker News, X, Bluesky, and Facebook. Use it to create monitored websites, manage keywords, review AI-scored mentions, preview keyword billing changes, and configure email alerts. The API never charges or changes the plan: plan changes happen in the RedReplier app.

Base URL: https://ai.redreplier.com/ai-app/api/v1

Send a RedReplier API token as a Bearer token on every request. Tokens start with redreplier_; RedReplier resolves the account from the token.

Authorization: Bearer redreplier_test_1234567890
Content-Type: application/json

The account is derived from the API token. Do not pass account or organization IDs. Every call runs in one workspace: without the optional X-Workspace-Id header it lands in the default workspace. An OAuth sign-in, such as the Claude or ChatGPT connector, can reach every workspace its member belongs to, across organizations. Call List workspaces to list them and send the id you want in X-Workspace-Id. An API key belongs to one workspace, so send its own id or leave the header out.

X-Workspace-Id: acct_7dK9pQ2

Start with List websites to discover website IDs and keyword IDs.

Core resources:

  • Website: product, domain, or brand being monitored.
  • Keyword: phrase matched across Reddit, Hacker News, X, Bluesky, and Facebook for a website.
  • Mention: matched post or comment from Reddit, Hacker News, X, Bluesky, or Facebook with a relevanceScore from 0 to 100.
  • Alert settings: email digest cadence for new relevant mentions.

Keyword statuses: PENDING, ACTIVE, DISABLED, SUSPENDED. Mention statuses: NEW, APPROVED, REJECTED.

REST endpoints

Errors

  • 400 Bad Request: Invalid input, URL, UUID, enum, query parameter, or body.
  • 401 Unauthorized: Missing or invalid Bearer token, or code: "token_issuer_lost_access" when the person who created the API key was deactivated or left the workspace.
  • 403 Forbidden: The X-Workspace-Id header names a workspace this credential cannot reach, including another workspace's id sent with an API key. The body carries code: "workspace_access_denied" and the workspaceId. A 403 with code: "subscription_required" means the workspace plan does not include API access. A 403 with code: "permission_denied" means your role in the workspace does not hold the permission the call needs: RedReplier needs redreplier.write, which Admin and Editor hold. That body names the requiredPermission and your role.
  • 404 Not Found: The resource does not exist for the token account.
  • 429 Too Many Requests: Rate limit exceeded. Every response carries RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a 429 adds Retry-After in seconds. Limits are counted per API key.
  • 500 Internal Server Error: Unexpected server error.

A refused workspace answers:

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "acct_3Hm8XwR",
  "message": "You have no access to workspace acct_3Hm8XwR. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}

Back to getting started