Public API reference

The RanklyBee Public API v1 is a scoped, read-only REST API for workspace integrations, reporting jobs, prospecting, outreach, and backlink reporting. The API operations are generated from the live OpenAPI contract and rendered inside this Fumadocs site. The machine-readable contract is available at /api/public/openapi.json.

Interactive endpoint reference

Use the API reference section in the sidebar to browse the grouped resource sections and see the GET method beside each endpoint. Each operation page includes request examples, response schemas, and an interactive playground.

Authentication

Create a scoped token in Settings → API access. Send the raw token in the Authorization header:

Authorization: Bearer rk_live_your_token

Tokens are shown only once and stored only as a hash. Store them in a server-side secret manager and never put them in browser code, URLs, logs, or public repositories.

Base URL and versioning

Production requests use:

https://api.ranklybee.com/api/public/v1

Local development uses http://localhost:3001/api/public/v1. The /v1 prefix is part of the public contract and future breaking changes will use a new version.

Rate limits

Each token can make up to 100 requests per minute. You can have up to 10 active tokens. Authenticated responses include:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current minute.
`X-RateLimit-Remaining`	Requests remaining in the current minute.
`X-RateLimit-Reset`	Unix timestamp when the current window resets.

When the limit is exceeded, the API returns 429 RATE_LIMIT_EXCEEDED and a Retry-After header. Wait until that interval before retrying.

Response format

Successful responses use a stable envelope:

{
  "ok": true,
  "data": { "id": "workspace_123" }
}

Errors use a stable machine-readable code. The message is intended for humans and may change:

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested workspace was not found."
  }
}

Endpoints

Get the current account

Returns the token owner, token metadata, workspace count, active token count, and current API limits.

curl https://api.ranklybee.com/api/public/v1/me \
  -H "Authorization: Bearer rk_live_your_token"

List workspaces

Requires the workspaces:read scope.

curl https://api.ranklybee.com/api/public/v1/workspaces \
  -H "Authorization: Bearer rk_live_your_token"

List websites

Requires the sites:read scope.

curl https://api.ranklybee.com/api/public/v1/workspaces/{workspaceId}/sites \
  -H "Authorization: Bearer rk_live_your_token"

List backlinks

Requires the backlinks:read scope. Results use one-based page pagination with a default limit of 25 and a maximum of 100. Use siteId and status to filter results. The legacy pageSize query parameter is also accepted.

curl "https://api.ranklybee.com/api/public/v1/workspaces/{workspaceId}/backlinks?page=1&limit=25" \
  -H "Authorization: Bearer rk_live_your_token"

Paginated responses include page, limit, total, and hasMore. Requests beyond the last page return an empty data array.

The interactive API reference also includes grouped read and write endpoints for workspace details, prospect discovery and pipeline status, contacts, drafts, inbox replies, blocked domains, discovery jobs, and individual backlinks. Backlink submissions are intentionally omitted because they are performed by the RanklyBee plugin automation rather than by this public API.

Error codes

Code	HTTP status	Meaning
`UNAUTHORIZED`	401	Missing, malformed, invalid, expired, or revoked token.
`SCOPE_REQUIRED`	403	The token does not include the required scope.
`NOT_FOUND`	404	The resource is not available to this account.
`VALIDATION_ERROR`	422	A query parameter is invalid.
`UPGRADE_REQUIRED`	402	A paid subscription or lifetime purchase is required.
`RATE_LIMIT_EXCEEDED`	429	The per-token request limit was exceeded.
`INTERNAL_ERROR`	500	Something failed on the server.

Use a development workspace when testing integrations. The API exposes the documented read-only data surface; dashboard, plugin automation, and administrative procedures remain private.

On this page