Skip to main content
POST
Add keyword to topic cluster
Add a keyword to an existing topic cluster. If the keyword doesn’t exist yet, it will be created automatically. A keyword can belong to only one topic per team; adding one that already sits in another topic returns 409 (single mode) or counts as skipped (bulk mode). Body: keyword (required in single mode), or items (bulk mode, one object per keyword). In single mode, countryId, languageId, locationCriteriaId, and locationCanonicalName are optional top-level fields; in bulk mode they go inside each items[] entry, and top-level values are not applied. track is always top-level (also start rank tracking, which uses your plan’s tracking allowance; a tracking failure does not undo the add). Single mode returns { success, keywordId, countryId, languageId, ... }. Bulk mode returns { success, requested, added, alreadyHere, skipped, keywordsNotTracked }.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Path Parameters

topicId
string
required

Topic cluster ID

Body

application/json
teamId
string

Team ID

keyword
string

Keyword text to add

countryId
string | null
languageId
string | null
locationCriteriaId
number | null

Google Ads location criteria ID for city/region-level tracking. Omit/null for country-only.

locationCanonicalName
string | null

Canonical location name paired with locationCriteriaId.

items
object[]

Bulk mode: one item per keyword. Items already linked to another topic are skipped.

track
boolean

Whether to also track this keyword for rank monitoring

Response

Default Response

success
boolean
keywordId
string
countryId
string | null
languageId
string | null
locationCriteriaId
number | null
locationCanonicalName
string | null
requested
number
added
number
alreadyHere
number
skipped
number
keywordsNotTracked
number