Getting started with the API
Create a least-privilege Rankability API key, make your first Agent API request, and choose the right endpoint family.
Last updated
Was this helpful?
Create a least-privilege Rankability API key, make your first Agent API request, and choose the right endpoint family.
Use the Rankability Agent API to connect external reporting tools, automations, AI assistants, and internal systems to your Rankability workspace. This guide covers the shared setup for every API family.
You need:
An active paid Rankability subscription.
A workspace owner or admin to create the API key.
A server-side application or secure automation environment. Do not expose an API key in browser code.
All customer Agent API endpoints start with:
https://app.rankability.com/api/agent/v1Current responses include X-API-Version: 1.8.0. There is no separate /v2 namespace.
Open organization Settings.
Select API keys.
Select Create API key.
Give the key a name that identifies its integration.
Select only the scopes the integration needs.
Set an expiration when the integration is temporary.
Copy the secret when Rankability displays it.
The full secret is shown once. Store it in a secrets manager or protected server environment. Rankability stores a hash and cannot reveal the secret later.
See Authentication and API scopes before granting write or run permissions.
Create a key with clients:read, then list the clients visible to your organization:
A successful response is organization-scoped and includes pagination:
Inspect these response headers while developing:
X-API-Version — the current Agent API contract version.
X-Request-Id — the identifier to include when reporting a failed request.
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset — the current key-level request allowance.
Resolve the active allowance or credit contract
GET /api/agent/v1/usage in API credits, rate limits, and errors
Research keyword opportunities
Score one existing page against search competitors
Run and inspect a full-site technical audit
Fetch pages or extract structured facts
Read tracking results or start a tracking scan
Create content jobs
Run a scored page audit
Query Google and AI-search results directly
Connect an AI assistant over MCP
Read the published in-app KB dataset
Use API use cases and integration patterns if you need help choosing between related surfaces.
Some endpoints, including Optimize, Scrape, and Extract, return their result in the same request. They may still take longer than an ordinary database read.
Researcher jobs, Tracker scans, Site Auditor crawls, Page Auditor audits, content jobs, and bounded crawls are asynchronous. For those operations:
Store the returned job, run, project, or audit ID.
Poll the documented read endpoint with backoff.
Stop at the documented terminal status.
Read the returned error and billing fields before retrying.
Current Rankability plans allow 30, 60, or 120 requests per minute per key for Core, Scale, and Agency respectively. Existing full-platform plans currently allow 60. Your response headers are authoritative; do not infer the limit from a plan name. Crawler operations also enforce daily page quotas, and some job families enforce concurrency limits.
Do not blindly retry write or run requests. Send Idempotency-Key where the endpoint supports it, store created IDs, and check whether the first request succeeded before creating another operation.
Continue with API credits, rate limits, and errors.
Last updated
Was this helpful?
Was this helpful?
curl "https://app.rankability.com/api/agent/v1/clients?limit=10" \
-H "Authorization: Bearer rk_live_YOUR_KEY"{
"clients": [],
"pagination": {
"limit": 10,
"offset": 0,
"count": 0,
"total": 0
}
}