Keywords API

The keywords API covers three jobs: managing keywords for a project (CRUD), generating new ideas via the research endpoint, and fanning existing keywords out into hundreds of long-tails with A→Z expansion. All endpoints live under /v1/... and are team-scoped via auth:sanctum.

Module context: Keyword Explorer · step-by-step guide: Keyword Research.

CRUD on the project

Keywords always belong to a project. Listing and creating happens project-scoped, deletion goes by ID.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"
PID=12

curl -X POST "$BASE/projects/$PID/keywords" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keyword":"ai content tools","language":"en","country":"US"}'

Research

The research endpoint returns related keyword ideas plus search volume, difficulty, and intent classification for a seed term.

curl -X POST "$BASE/keywords/research" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"seed":"ai writing","language":"en","country":"US","project_id":12}'

Response: list with keyword, search_volume, kd_score, intent. If project_id is provided, the hits are persisted directly on the project and become available via GET /v1/projects/{project}/keywords.

A deeper SERP drilldown (volume trends, SERP URLs, related, questions) goes through POST /v1/explorer and GET /v1/explorer/{keyword} — see Keyword Explorer.

A→Z expansion (async)

Systematically generates long-tail variations along question patterns, modifiers, and alphabet suffixes. Runs asynchronously, since a single seed keyword can produce 200–500 long-tails.

# Start expansion
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# Poll results (job runs 2–3 min)
curl "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN"

Response 202 Accepted:

{
  "keyword_id": 481,
  "status": "pending",
  "message": "Expansion dispatched"
}

In addition to keyword and search_volume, each item in expansions[] also has a cluster_label — that lets you group related long-tails into topic clusters that later serve as briefings for article generation (Articles API → POST /articles/{id}/generate).

Complete example: seed → cluster → article briefs

PID=12

# 1) Research seed
curl -s -X POST "$BASE/keywords/research" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"seed":"ai content tools","project_id":'$PID'}'

# 2) Identify best-fit keyword (e.g. highest volume with KD < 40)
KW=$(curl -s "$BASE/projects/$PID/keywords" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '[.data[] | select(.kd_score < 40)] | sort_by(-.search_volume) | .[0].id')

# 3) Start A→Z expansion
curl -X POST "$BASE/keywords/$KW/expand" \
  -H "Authorization: Bearer $TOKEN"

# 4) Poll, then evaluate clusters
sleep 120
curl -s "$BASE/keywords/$KW/expansions" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data | group_by(.cluster_label) | map({cluster: .[0].cluster_label, count: length})'

Notes & pitfalls

• Expand is async. Even with a 202 returned — long-tails only appear after the job completes. Polling interval: 30–60 s.
• Research persists only with project_id. Without project_id the call is a one-shot — the ideas live in the response, not in the DB.
• Expansion builds on an existing keyword. First CRUD/research, then expand against the returned ID.
• No bulk delete. Deleting multiple keywords in parallel requires multiple DELETE calls.

Related: Projects API · Credits · Keyword Explorer · Keyword Research.