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
Section titled “1. Create an API key”- 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.
- 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.
- 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.
export RANKABILITY_API_KEY="rk_live_..."2. Make your first call
Section titled “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.
curl https://app.rankability.com/api/agent/v1/usage \ -H "Authorization: Bearer $RANKABILITY_API_KEY"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());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.
3. Find or create a client
Section titled “3. Find or create a client”Most work happens inside a client workspace. List the ones you have (scope clients:read):
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:
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
Section titled “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):
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:
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:
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.
5. Build it properly
Section titled “5. Build it properly”- Retry safely. Send a stable
Idempotency-Keyon 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-RemainingandX-RateLimit-Reset. On429 rate_limit_exceeded, wait forRetry-Afterseconds. 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.jsoninto Postman, n8n, Make or a client generator rather than hand-writing request shapes.
Next steps
Section titled “Next steps”- Browse every endpoint in the API reference, and try requests from the browser with your key.
- Connect an AI assistant with the MCP server.
- Read the module guides, starting with what the API can do.
