Skip to content

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 a free developer account. It comes with 300 free credits, and the API Dashboard opens when you’re done. On a Rankability plan, open Settings > API & MCP 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 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.

Terminal window
export RANKABILITY_API_KEY="rk_live_..."

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.

cURL
curl https://app.rankability.com/api/agent/v1/usage \
-H "Authorization: Bearer $RANKABILITY_API_KEY"
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
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.

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

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

Terminal window
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:

Terminal window
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.

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):

Terminal window
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:

Terminal window
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:

Terminal window
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.

  • 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.
  • Log the request ID. Every response has an X-Request-Id. Include it when you contact support.
  • Use the spec. Import openapi.json into Postman, n8n, Make or a client generator rather than hand-writing request shapes.