API reference

What the API is#

The API gives you the same data as the app, in your own tools. It is a small, versioned REST API under https://app.rankfinity.app/api/v1.

• Reads return what you see in the app: projects, keyword positions, rank history, AI Visibility summary, site audit summary, backlink summary, and your credit balance.
• Writes add keywords for free, and start two paid actions: a rank check and an AI Visibility run.
• Money is credits. The API never returns dollars and never names the data suppliers.

The machine-readable description (OpenAPI 3) is at /api/v1/openapi.json. It lists only the /api/v1 endpoints.

Create a key#

1. Open My account › API & feeds.
2. Enter a name (for example "Looker dashboard") and choose the scope.
3. Click Create key and copy it. The key is shown once. Rankfinity stores only a hash, so a lost key cannot be shown again. Create a new one and revoke the old one.

Client accounts can create read keys only. Changes are made by the agency. You can have up to 10 active keys. Revoking a key takes effect immediately.

Authenticate#

Send the key as a bearer token on every request:

Authorization: Bearer rk_...

A missing, malformed, revoked or expired key returns 401. A key that is valid but sent too often returns 429 with a Retry-After header.

Rate limit#

Each key has its own limit per minute (the operator sets it; the default is 60). Requests above it return 429. Wait for Retry-After seconds and try again.

Endpoints#

Replace {pid} with the project id from GET /api/v1/projects.

A project that is not yours returns 404, the same as a project that does not exist.

Empty is not zero#

A position with "rank": null and "measured": false means the check did not finish, not that the keyword is out of the top results. "measured": true with a null rank means the site was not found in the depth that was searched. A backlink or audit summary with "available": false means that step has not run yet, and the response says why.

Paid calls: check the price first#

Paid writes take expected_credits. That number must be the price you saw in the matching estimate call.

1. GET /api/v1/projects/{pid}/rank-checks/estimate returns "credits": 42.
2. POST /api/v1/projects/{pid}/rank-checks with body {"expected_credits": 42} starts the check and charges 42 credits.

If the price has changed in the meantime, nothing is charged and the call returns 409 with the new price. Check it and send the request again. If expected_credits is missing, the call returns 422. If the balance is too low, it returns 402 with the amount needed.

Example#

KEY="rk_..."
curl -s -H "Authorization: Bearer $KEY" \
  https://app.rankfinity.app/api/v1/projects/12/keywords?limit=20

curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"expected_credits": 42}' \
  https://app.rankfinity.app/api/v1/projects/12/rank-checks

Errors#

Google Sheets and Looker Studio#

For spreadsheets and dashboards that refresh by themselves, use the CSV feeds instead of the API. See Feeds for Sheets and Looker Studio.