Getting started with the API

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.

Before you begin

You need:

• An active paid Rankability subscription.
• An organization 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/v1

Current responses include X-API-Version: 1.23.0. There is no separate /v2 namespace.

A machine-readable OpenAPI 3.0 description of the customer Agent API is published at https://app.rankability.com/api/openapi.json (also available at /api/agent/v1/openapi.json). It needs no API key, so you can load it into an API client or code generator. It lists each route’s method, path, and required scopes; authentication, limits, and pricing still apply to the requests you make.

1. Create a least-privilege key

1. Open organization Settings.
2. Select API keys.
3. Select Create API key.
4. Give the key a name that identifies its integration.
5. Select only the scopes the integration needs.
6. Set an expiration when the integration is temporary.
7. 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.

2. Make a read-only request

Create a key with clients:read, then list the clients visible to your organization:

curl "https://app.rankability.com/api/agent/v1/clients?limit=10" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

A successful response is organization-scoped and includes pagination:

{
  "clients": [],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 0,
    "total": 0
  }
}

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.

3. Choose the correct API family

Goal	Start with
Read pooled usage windows and recovery times	GET /api/agent/v1/usage in API usage, rate limits, and errors
Research keyword opportunities	Researcher API
Score one existing page against search competitors	Optimize API
Run and inspect a full-site technical audit	Site Auditor API
Fetch pages or extract structured facts	Scrape, Crawl, and Extract API
Read tracking results or start a tracking scan	Tracker API onboarding
Create content jobs	Creating content jobs
Manage saved outreach lists and pipeline items	Prospector API
Read saved backlink profile evidence	Backlink Profile API
Read saved GBP or Batch URL audit artifacts	GBP Auditor guide and Batch URL Analyzer guide
Inspect recurring Routines or publishing delivery state	Connecting Rankability to AI assistants with MCP and Exporting and publishing content
Run a scored page audit	Page Auditor API endpoints
Query Google and AI-search results directly	Search Intelligence API endpoints
Connect an AI assistant over MCP	Connecting Rankability to AI assistants with MCP
Read the published in-app KB dataset	Knowledge Base API endpoint

Use API use cases and integration patterns if you need help choosing between related surfaces.

4. Handle synchronous and asynchronous work differently

Scrape and Extract return their result in the same request. They may still take longer than an ordinary database read.

Researcher jobs, Optimize runs, Tracker scans, Site Auditor crawls, Page Auditor audits, content jobs, and bounded crawls are asynchronous. For those operations:

1. Store the returned job, run, project, or audit ID.
2. Poll the documented read endpoint with backoff.
3. Stop at the documented terminal status.
4. Read the returned error and usage fields before retrying.

5. Prepare for limits and failures

Each key has a per-minute request limit that depends on your plan; see the table in API usage, rate limits, and errors. Your response headers are authoritative. 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 usage, rate limits, and errors.