> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-getting-started.md). # 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.15.0`. There is no separate `/v2` namespace. ## 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](/api/api-authentication.md) 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: ```bash 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: ```json { "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](/api/api-credits-rate-limits-and-errors.md) | | Research keyword opportunities | [Researcher API](/api/api-researcher.md) | | Score one existing page against search competitors | [Optimize API](/api/api-optimize-endpoint.md) | | Run and inspect a full-site technical audit | [Site Auditor API](/api/api-site-auditor.md) | | Fetch pages or extract structured facts | [Scrape, Crawl, and Extract API](/api/api-crawler.md) | | Read tracking results or start a tracking scan | [Tracker API onboarding](/api/api-reporter-getting-started.md) | | Create content jobs | [Creating content jobs](/api/api-creating-content-jobs.md) | | Manage saved outreach lists and pipeline items | [Prospector API](/api/api-prospector.md) | | Read saved backlink profile evidence | [Backlink Profile API](/api/api-backlink-profile.md) | | Read saved GBP or Batch URL audit artifacts | [GBP Auditor guide](/audit/gbp-auditor-guide.md) and [Batch URL Analyzer guide](/audit/batch-url-analyzer-guide.md) | | Inspect recurring Routines or publishing delivery state | [Connecting Rankability to AI assistants with MCP](/api/mcp-getting-started.md) and [Exporting and publishing content](/copywriter/exporting-your-content.md) | | Run a scored page audit | [Page Auditor API endpoints](/api/api-page-auditor.md) | | Query Google and AI-search results directly | [Search Intelligence API endpoints](/api/api-search-intelligence.md) | | Connect an AI assistant over MCP | [Connecting Rankability to AI assistants with MCP](/api/mcp-getting-started.md) | | Read the published in-app KB dataset | [Knowledge Base API endpoint](/api/api-knowledge-base.md) | Use [API use cases and integration patterns](/api/api-use-cases.md) 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 Current plans allow 30, 60, or 120 requests per minute per key, depending on the plan. 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 usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md).