REST API & Tokens

Everything you can do in the Grandranker dashboard (articles, keywords, content planning, rank tracking, AI visibility, webhooks and more) is also available over a REST API. This page covers creating a token and authenticating. The full endpoint reference with request/response examples is at https://app.grandranker.com/docs.

Creating an API token

1. Go to Settings → API Tokens at https://app.grandranker.com/settings/api-tokens.
2. In the Create API Token card, enter a Token Name (e.g. "WordPress Plugin").
3. Pick the Scopes the token needs. Use Select all or check individual scopes. At least one is required.
4. Click Create Token.
5. Copy the token from the confirmation card. It won't be shown again. Store it somewhere safe.

Tokens don't expire. They belong to your user account, and the Active Tokens card lists each one with its creation date, scopes and last-used time. Revoke a token any time with the trash button. Revocation is immediate and cannot be undone.

Authenticating

• Base URL: https://app.grandranker.com/api/v1
• Auth header: Authorization: Bearer <your token>
• Website scoping: most endpoints operate on one website, selected via the X-Domain-ID header. Without it you get 400 X-Domain-ID header is required. List your website IDs with GET /api/v1/domains.

A quick smoke test:

Copycurl https://app.grandranker.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Then list your websites to find the ID to pass as X-Domain-ID:

Copycurl https://app.grandranker.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Rate limits and requirements

• Read and write endpoints: 60 requests per minute.
• Expensive operations (e.g. triggering audits or generation): 10 requests per minute.
• An active subscription is required. Without one, the API returns 402 Active subscription required to use the API.
• Endpoints for features your plan doesn't include return an error until the feature is available on your plan.

Connecting an AI agent (MCP)

Grandranker also ships an MCP server so AI agents (Claude, Cursor and others) can drive your account directly. The Connect an AI agent (MCP) card on the API Tokens page shows the endpoint (https://app.grandranker.com/mcp/grandranker) and a ready-to-copy client config that authenticates with the same bearer token:

Copy{
  "mcpServers": {
    "grandranker": {
      "url": "https://app.grandranker.com/mcp/grandranker",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Endpoint reference

The interactive API documentation at https://app.grandranker.com/docs covers every endpoint with parameters, example requests in bash/JavaScript/PHP, and example responses. An OpenAPI 3 spec and a Postman collection are available there too.

If you want Grandranker to push data to you instead of polling the API, set up a webhook.

Questions? Contact us at [email protected].