1. Create an API key
In the dashboard, go to Settings → API Keys and create one. Copy it immediately — the full key is shown once. See Create an API key.2. Verify it works
id is the orgId for organization-scoped paths.
Only organizations whose membership you’ve accepted are listed. A pending invitation doesn’t appear and doesn’t grant access.
3. List projects
meta:
4. Everything else is under /v1/projects
This is the part worth internalising: only project list and create are nested under an organization. Every other project resource sits at the top level, with the organization derived from the project:5. Add tracked keywords
location_code 2840 is the United States and language_code en is English — the same defaults the dashboard uses. Keywords are lower-cased and de-duplicated, so submitting overlapping lists is safe.
New keywords have no position until their project’s next rank check.
6. Billable calls need an explicit organization
Some endpoints have neither an organization nor a project in the path — live SERP lookups, keyword research, content generation, trends:org_id as a query parameter. Omitting it returns BAD_REQUEST: “org_id is required. This call is billed to an organization, so it cannot be inferred.”
With an API key it’s inferred from the key, and you can omit it.
Handling responses
Always checksuccess:
data — a successful DELETE returns data: null.
What to expect from the data
Most endpoints return stored data from the last background collection, not a live lookup. Reading rankings returns the last completed check; it doesn’t trigger a new one. Endpoints that start work return a job to poll. See Jobs and polling.Next
- Authentication — keys, tokens, and what each can do
- Organizations and scoping
- Errors
- Pagination —
per_pagegoes to 500