REST API

Authentication, resources, pagination, and error handling for the RankNest REST API.

The RankNest REST API gives scripts and integrations the same data you see in the dashboard: clients, experiments, link maps, tasks, and more. It is a plain JSON API over HTTPS. Anything your account can see in the dashboard, the API can read; anything it can't, the API can't either.

The CLI and the MCP server are wrappers around this API, so everything on this page applies to them too.

Base URL and authentication

All requests go to:

https://www.ranknest.io/api/v1

Always use the www subdomain. Requests to the bare domain are redirected in a way that strips the authorization header, so they return 401.

Authenticate every request with a Personal Access Token in the Authorization header:

curl "https://www.ranknest.io/api/v1/clients" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX"

Send request bodies as JSON with a Content-Type: application/json header.

Resources

Most resources follow the same pattern: GET /resource lists, POST /resource creates, and GET, PUT, and DELETE on /resource/:id read, update, and delete a single record. List endpoints accept filter parameters such as client_id and status where they make sense.

/clients: your client records.
/experiments: SEO tests, filterable by client_id and status.
/experiment-pages: the pages experiments run on. One page can hold several tests over time.
/link-maps: link maps, with nested resources under each map: /link-maps/:id/nodes, /edges, /topic-groups, and /recommendations.
/tasks: client tasks, filterable by client_id, status, and completed.
/seo-variables: your custom SEO test variables.
/site-audits: audit runs and their results.
/site-connectors: connections to client websites, with /site-connectors/:id/pages for pages the connector has reported and /site-connectors/:id/implementation-queue for queued link changes (see below). /verify and /sync actions live under the connector too.
/campaigns: Message Mining campaigns, with /campaigns/:id/entries for the collected reviews.
/content-batches: Content Mapping batches, with /content-batches/:id/pages for the analyzed pages.
/blog-articles: the RankNest blog, read-only.
/users/:id: your own profile only.
/health: a quick connectivity check that returns your record counts.
/functions/*: typed endpoints that start jobs such as a site crawl, an audit, or a Linking Plan generation.

Responses and pagination

Single-record endpoints return the object directly. Creates return the new object with status 201.

List endpoints are paginated with two query parameters: page (starts at 1) and limit (default 50, maximum 100). They return the rows in data plus a pagination block:

{
  "data": [ { "id": "..." } ],
  "pagination": { "total": 132, "page": 1, "limit": 50, "pages": 3 }
}

Use pages to know when to stop, or keep requesting until data comes back empty.

Errors

Errors return a JSON body with a single error field:

{ "error": "client_id is required" }

Common status codes:

400: a required field is missing or a value is invalid.
401: the token is missing, revoked, mistyped, or the request went to the bare domain instead of www.
403: your account can't do this, for example a feature that needs an admin role.
404: the record doesn't exist or belongs to another account. The API never reveals which.
409: the request conflicts with existing data, for example creating a test on a URL that already has an active test, or queueing a recommendation that is already queued.
429: a plan limit was reached (see below), or the token went over its rate limit of 120 requests per minute. The message tells you which, and when the rate window resets.

Plan limits

Create endpoints enforce the same subscription limits as the dashboard. The API, CLI, and MCP server share one set of caps with the app, so a client or test you can't create in the dashboard can't be created here either. When a limit is hit, the response is status 429 and the body includes your limit, used, and remaining counts. See Pricing for your plan's limits.

Worked examples

List your clients:

curl "https://www.ranknest.io/api/v1/clients?limit=10" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX"

Create a task for a client:

curl -X POST "https://www.ranknest.io/api/v1/tasks" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "CLIENT_UUID",
    "title": "Review March linking plan",
    "priority": "high",
    "due_date": "2026-08-15"
  }'

The response is the created task with status 201.

The implementation queue for custom sites

The Site Connector auto-implements Linking Plan recommendations on WordPress. For custom-coded sites, the implementation queue is the API equivalent: RankNest queues the link change, your own tooling applies it, then reports back.

List the queued items for a connector:

curl "https://www.ranknest.io/api/v1/site-connectors/CONNECTOR_UUID/implementation-queue?status=queued" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX"

Each item describes one link to add: the source page, the target URL, and the anchor text.

Apply the link in your site's codebase however your stack does it.
Report the outcome by updating the item:
```
curl -X PATCH "https://www.ranknest.io/api/v1/site-connectors/CONNECTOR_UUID/implementation-queue/ITEM_UUID" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'
```
Marking an item completed also marks its linked recommendation as implemented in the Linking Plan, the same way the WordPress plugin does. Use failed with an error_message if the change couldn't be applied, or reverted if you later undid it.

Tip: This flow works well from an AI coding assistant connected over MCP: it can list the queue, edit your codebase, and report completion in one session. See MCP Server Setup.

Last updated 2026-07-31