Skip to main content
The Surnex REST API is available at https://api.surnex.io/v1. Everything the dashboard does, it does through this API.

​
Base URL

​
Authentication

Send an API key in the X-API-Key header:
The key resolves to one organization. See Authentication.

​
Response format

Every successful response is wrapped:
List endpoints add pagination metadata:
Errors use the same envelope with success: false:
Check success rather than inferring from the presence of data — a successful DELETE returns data: null.

​
Resources

The API covers the full platform: The API Reference section of these docs is generated from the live OpenAPI schema at https://api.surnex.io/openapi.json, so it’s always current.

​
Path shape

Only listing and creating projects is nested under an organization. Every other project resource is addressed by project id, with the organization derived from it:
A third group has neither in the path — live lookups, research, trends, content. Those are billable, so a user token must name the organization with an org_id query parameter; an API key infers it. Anything you can’t reach answers 404, not 403. See Organizations and scoping.

​
Stored data, not live lookups

Most endpoints return data collected in the background, not fetched at request time. A rankings endpoint returns the last completed rank check. Endpoints that start work — audits, backlink refreshes, web vitals — return immediately with a job, and you poll for the result. See Jobs and polling. Getting this wrong is the most common source of confusion: an endpoint returning yesterday’s numbers isn’t broken, it’s returning what was last collected.

​
Rate limits

Requests are limited per credential, per minute — 120 for an API key, 60 for a user session. Lower than you might assume, so raise per_page when paginating. See Rate limits.

​
Next

Quickstart

Your first authenticated request.

Authentication

Keys, JWTs, and scope.

Jobs and polling

How background work is reported.

Errors

Every error code and what to do about it.