REST API & Tokens

Everything 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. Full endpoint reference: https://app.grandranker.com/docs.

Creating an API token

1. Go to Settings → API Tokens at https://app.grandranker.com/settings/api-tokens.
2. Enter a Token Name in the Create API Token card.
3. Pick the Scopes the token needs (Select all or individual scopes — at least one required).
4. Click Create Token.
5. Copy the token from the confirmation card. It won't be shown again.

Tokens don't expire. Active Tokens lists each one with creation date, scopes and last-used time. Revoke any time with the trash button — immediate, no undo.

Authenticating

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

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

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 (audits, generation): 10 requests per minute.
• Requires an active subscription — otherwise 402 Active subscription required to use the API.
• Endpoints for features your plan doesn't include return an error until upgraded.

Connecting an AI agent (MCP)

Grandranker ships an MCP server so AI agents (Claude, Cursor, 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 client config using the same bearer token:

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

Endpoint reference

The interactive docs at https://app.grandranker.com/docs cover every endpoint with parameters, example requests (bash/JavaScript/PHP) and responses, plus an OpenAPI 3 spec and a Postman collection.

To have Grandranker push data to you instead of polling, set up a webhook.