Skip to main content

Quickstart

Get from zero to your first successful Ranktracker API request in a few minutes. You'll create an API key, list your tracked domains, and learn how to read the JSON:API response.

:::note What you'll need An active Ranktracker account with API access enabled on your plan, and a terminal with curl (or any HTTP client). Every example uses the production base URL https://api.ranktracker.com, and all endpoints live under /v1. :::

1. Get an API key​

API keys are created and managed in the Ranktracker app:

  1. Sign in at app.ranktracker.com.
  2. Open your account settings and go to the API keys section.
  3. Create a new key and copy it. It looks like tkn_usr_....

:::warning Treat your key like a password Your key grants full access to your account's data. Keep it secret and server-side — never commit it to source control or ship it in browser or mobile code. Keys currently have no scopes and no expiry, so the only way to revoke access is to delete the key in the app. See the Authentication guide for the full details. :::

2. Make your first request​

Send the key in the Authorization header — with no Bearer prefix — and call GET /v1/domains to list the domains you track:

curl https://api.ranktracker.com/v1/domains \
  -H "Authorization: tkn_usr_your_api_key_here"

Here's the same request in Python and Node.js:

import requests

resp = requests.get(
    "https://api.ranktracker.com/v1/domains",
    headers={"Authorization": "tkn_usr_your_api_key_here"},
)
resp.raise_for_status()
print(resp.json()["data"])
const resp = await fetch("https://api.ranktracker.com/v1/domains", {
  headers: { Authorization: "tkn_usr_your_api_key_here" },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const body = await resp.json();
console.log(body.data);

A 200 OK means you're connected. If you get a 403, either the key is missing/invalid or your plan doesn't have API access enabled — check the Errors & rate limits guide for the full list of status codes.

3. Read the response​

Responses use the JSON:API envelope. A list endpoint returns an array under data; each entry has an id, a type, and its fields nested under attributes in camelCase. Here's a trimmed response from GET /v1/domains:

{
  "data": [
    {
      "id": "3f2a9c8e-1d4b-4a7f-9e2c-8b1a2c3d4e5f",
      "type": "domain",
      "attributes": {
        "domain": "example.com",
        "scheme": "https",
        "host": "www.example.com",
        "matchType": "any",
        "projectName": "Example Site",
        "colour": "#4f46e5",
        "keywordMonitor": true,
        "createdAt": "2026-01-14T09:31:07Z",
        "updatedAt": "2026-06-30T22:05:44Z"
      }
    }
  ]
}

A few things to notice, because they hold for every resource in the API:

  • data holds the resource — an array for list endpoints like this one, or a single object for endpoints that return one record (for example GET /v1/domains/{uuid}).
  • id is the resource's UUID. You'll pass it back in the path to read, update, or nest under a domain — e.g. GET /v1/domains/{uuid}/keywords.
  • attributes holds the fields, and their keys are camelCase (projectName, keywordMonitor, createdAt) even though the request body you send on writes uses snake_case. Keep that asymmetry in mind.

:::tip Pagination List endpoints accept page and per_page (max 1000) query parameters and return the totals in X-Total-Count, X-Total-Pages, X-Per-Page, and X-Current-Page response headers. See the Pagination guide to page through large result sets. :::

Next steps​

You've made your first authenticated request. From here: