---
title: "Quickstart"
description: "Create an API key, make your first call and start real work with the Rankability Agent API in about five minutes."
canonical_url: "https://developers.rankability.com/quickstart"
section: "Get started"
last_updated: 2026-11-16
---

# Quickstart

Create an API key, make your first call and start real work with the Rankability Agent API in about five minutes.

Every request goes to `https://app.rankability.com/api/agent/v1` with an organization API key in the `Authorization` header. Responses are JSON.

## 1. Create an API key

1. [Create a free developer account](https://app.rankability.com/developer/sign-up). It comes with 300 free credits, and the [API Dashboard](https://app.rankability.com/developer) opens when you're done. On a Rankability plan, open [Settings > API & MCP](https://app.rankability.com/settings?tab=api-keys) in the app instead.
2. Select **Create API key**, name it after the integration (for example "n8n content pipeline"), and choose only the scopes it needs. The [scope list](/guides/authentication#scopes) explains each one.
3. Copy the key. It starts with `rk_live_` and is shown once.

Store it as a secret, such as an environment variable. Never commit it or ship it in browser code.

```bash
export RANKABILITY_API_KEY="rk_live_..."
```

> **No plan needed:** Pay per call with prepaid credits, or use the API on any paid Rankability plan. Keys, credits and usage are managed in the API Dashboard, not on this site. See [Pricing and limits](/pricing).
## 2. Make your first call

`GET /usage` is read-only and safe to call any time. It confirms the key works, shows which organization it belongs to and reports the usage you have left. Call it before starting work.

```bash title="cURL"
curl https://app.rankability.com/api/agent/v1/usage \
  -H "Authorization: Bearer $RANKABILITY_API_KEY"
```

```js title="JavaScript (Node 18+)"
const response = await fetch("https://app.rankability.com/api/agent/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.RANKABILITY_API_KEY}` },
});
console.log(response.status, await response.json());
```

```python title="Python"
import os, requests

response = requests.get(
    "https://app.rankability.com/api/agent/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['RANKABILITY_API_KEY']}"},
)
print(response.status_code, response.json())
```

A `200` with your organization's `id` and `name` means you are connected. A `401` means the key is missing, mistyped or revoked; a `403` means the key lacks the scope or the organization has no active plan. See [Errors](/guides/errors).

`GET /usage` needs the `copywriter:read` or `copywriter:run` scope.

## 3. Find or create a client

Most work happens inside a client workspace. List the ones you have (scope `clients:read`):

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

Or create one (scope `clients:write`). Send an `Idempotency-Key` so a retry cannot create it twice:

```bash
curl -X POST https://app.rankability.com/api/agent/v1/clients \
  -H "Authorization: Bearer $RANKABILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-acme-plumbing" \
  -d '{"name": "Acme Plumbing", "domain": "acmeplumbing.com"}'
```

Keep the returned client `id`.

## 4. Start real work

Long-running work is asynchronous: you start a job, get an ID back right away, and poll it. This example writes an article in `auto` mode (scope `copywriter:run`):

```bash
curl -X POST https://app.rankability.com/api/agent/v1/copywriter/jobs \
  -H "Authorization: Bearer $RANKABILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-water-heater-guide" \
  -d '{
    "client_id": "CLIENT_ID",
    "topic": "how long does a water heater last",
    "intent": "educate",
    "page_contract": "article",
    "mode": "auto"
  }'
```

Poll the job until `status` is `completed` (scope `copywriter:read`), every 30 to 60 seconds:

```bash
curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID \
  -H "Authorization: Bearer $RANKABILITY_API_KEY"
```

Then fetch the finished article, SEO metadata and FAQ schema:

```bash
curl https://app.rankability.com/api/agent/v1/copywriter/jobs/JOB_ID/artifacts \
  -H "Authorization: Bearer $RANKABILITY_API_KEY"
```

A completed article draws on your plan's usage. Check the cost first with `GET /usage/estimate`, described in [Usage and allowances](/guides/usage).

## 5. Build it properly

- **Retry safely.** Send a stable `Idempotency-Key` on every create call so a network retry returns the original job instead of starting a second one.
- **Respect rate limits.** Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. On `429 rate_limit_exceeded`, wait for `Retry-After` seconds. Limits are on [Pricing and limits](/pricing).
- **Log the request ID.** Every response has an `X-Request-Id`. Include it when you contact support.
- **Use the spec.** Import [`openapi.json`](https://app.rankability.com/api/openapi.json) into Postman, n8n, Make or a client generator rather than hand-writing request shapes.

## Next steps

- Browse every endpoint in the [API reference](/api-reference), and try requests from the browser with your key.
- Connect an AI assistant with the [MCP server](/mcp).
- Read the module guides, starting with [what the API can do](/guides/overview).
