Keywords

Read the keyword library, import keywords at scale, get instant AI suggestions, and queue AI keyword generation.

Each site has a keyword library: the queue of topics RankPine turns into articles. Keywords carry estimated volume, difficulty, and search intent.

List keywords

GET /api/v1/sites/{site_id}/keywords?status=planned&search=&page=1&per_page=20

Param	Notes
`status`	`planned` · `in_progress` · `done` · `skipped`
`search`	Substring match on the keyword text
`page`, `per_page`	Standard pagination (max 100 per page)

{
  "data": [
    {
      "id": "7b21…",
      "keyword": "best analytics for indie hackers",
      "status": "planned",
      "intent": "commercial",
      "volume": 320,
      "difficulty": 24,
      "source": "auto",
      "metric_source": "dataforseo",
      "priority": 42,
      "created_at": "2026-06-11T08:00:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 143
}

volume/difficulty are null for a short while after import — enrichment runs asynchronously.

Import keywords at scale

POST /api/v1/sites/{site_id}/keywords

{ "keywords": ["keyword one", "keyword two", "…up to 500 per request"] }

Duplicates (case-insensitive) are skipped, metrics are enriched asynchronously, and the site's monthly import limit applies with partial acceptance:

{
  "added": 48,
  "duplicates": 2,
  "rejected_over_limit": 0,
  "monthly_remaining": 2,
  "keywords": ["…the inserted rows…"]
}

Returns 201. When the monthly limit is already spent you get 403 keyword_limit_reached.

Suggest keywords (synchronous)

Instant AI suggestions based on the site's niche, description, and existing library — nothing is saved; import the winners yourself.

POST /api/v1/sites/{site_id}/keywords/suggest

{ "topic": "self-hosted analytics", "count": 10 }

Both fields are optional (defaults: whole-site focus, 10 suggestions, max 25).

{
  "suggestions": [
    {
      "keyword": "self hosted google analytics alternative",
      "intent": "commercial",
      "rationale": "High purchase intent from privacy-conscious teams comparing options."
    }
  ],
  "note": "Suggestions are not saved. Import the ones you want via POST /v1/sites/{site_id}/keywords."
}

Rate limit: 30/hour per key (burst 5/minute) — this endpoint runs a model call synchronously.

Generate keywords (asynchronous)

Queue RankPine's full research pass — competitors, Search Console (when connected), topic clusters:

POST /api/v1/sites/{site_id}/keywords/generate

Returns 202 with mode "plan" (empty library → full keyword plan) or "top_up" (fresh additive batch). Poll the list endpoint for new rows.

Delete keywords

DELETE /api/v1/sites/{site_id}/keywords/{keyword_id}

POST /api/v1/sites/{site_id}/keywords/bulk-delete

{ "ids": ["7b21…", "9c44…"] }

Responds { "deleted": 2 }.