Resources

Keywords

Tracked keywords with positions, search volume, difficulty, intent, target URL and approval status.

GET/api/v1/keywordsRead key

List keywords

Authentication: Bearer API key in the Authorization header.

Parameters
Parameter	In	Type	Description
websiteId	query	string	Filter by website
groupId	query	string	Group ID or 'none'
position	query	top3 \| top10 \| 11-20 \| 21-100 \| unranked	Position bucket
movement	query	improved \| declined \| new \| lost	Change since previous collection
status	query	active \| pending \| approved \| rejected \| paused	Approval status
device	query	desktop \| mobile \| tablet	Device
q	query	string	Keyword contains

Request

curl "https://rankspire.tech/api/v1/keywords" \
  -H "Authorization: Bearer $RANKSPIRE_KEY"

Response

{
  "data": [{
    "id": "cm1kw…", "websiteId": "cm1site9x0001", "keyword": "best hiking boots",
    "position": 4, "previousPosition": 7, "bestPosition": 3,
    "rankingUrl": "https://example.com/boots", "targetUrl": "https://example.com/boots",
    "searchVolume": 18100, "difficulty": 62, "cpc": 1.84, "intent": "commercial",
    "status": "approved", "device": "desktop", "country": "US"
  }],
  "meta": { "total": 376, "limit": 100, "offset": 0 }
}

POST/api/v1/keywordsRead & write key

Add keywords

Authentication: Bearer API key in the Authorization header.

Parameters
Parameter	In	Type	Description
websiteId*	body	string	Website
keywords*	body	string[]	Up to 2,000 per request
groupId	body	string	Group to assign
device	body	desktop \| mobile \| tablet	Default desktop
country	body	string	Default US
targetUrl	body	string	Page that should rank

Request

curl -X POST "https://rankspire.tech/api/v1/keywords" \
  -H "Authorization: Bearer $RANKSPIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "websiteId": "cm1site9x0001", "keywords": ["hiking boots sale", "waterproof hiking boots"], "device": "mobile" }'

Response

{ "data": { "added": 2, "skipped": 0 } }

402 payment_required keyword limit reached

PATCH/api/v1/keywordsRead & write key

Bulk update keywords

Authentication: Bearer API key in the Authorization header.

Parameters
Parameter	In	Type	Description
ids*	body	string[]	Keyword IDs
patch*	body	object	groupId, status, intent and/or targetUrl

Request

curl -X PATCH "https://rankspire.tech/api/v1/keywords" \
  -H "Authorization: Bearer $RANKSPIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["cm1kw…"], "patch": { "status": "approved", "groupId": "cm1grp…" } }'

Response

{ "data": { "updated": 1 } }

DELETE/api/v1/keywordsRead & write key

Remove keywords

Authentication: Bearer API key in the Authorization header.

Parameters
Parameter	In	Type	Description
ids*	body	string[]	Keyword IDs

Request

curl -X DELETE "https://rankspire.tech/api/v1/keywords" \
  -H "Authorization: Bearer $RANKSPIRE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["cm1kw…"] }'

Response

{ "data": { "deleted": 1 } }