Skip to main content
Manage keyword research programmatically: list, add, delete, star, bulk-update, trigger research, and manage groups. Function: public-api-keywords Base path: https://app.keupera.com/api/v1/public-api-keywords

​
List keywords

GET /keywords
ParameterTypeDefaultDescription
website_idUUIDAPI key’s websiteTarget website
limitinteger100Results per page
pageinteger1Page number
statusstring—Filter by status (active, planned, ignored)
group_idUUID—Filter by keyword group

​
Response

{
  "data": [
    {
      "id": "uuid",
      "term": "best seo tools",
      "volume": 12000,
      "difficulty": 45,
      "cpc": 2.50,
      "intent": "Commercial",
      "opportunity": "High",
      "status": "active",
      "is_starred": false,
      "funnel_stage": "consideration",
      "language": "en",
      "group_id": "uuid",
      "keyword_groups": { "id": "uuid", "name": "SEO Tools" },
      "blog_posts": { "id": "uuid", "title": "Best SEO Tools in 2024", "status": "published" },
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": { "total": 150, "page": 1, "limit": 100 }
}

​
Add keywords

POST /keywords

​
Request body

{
  "website_id": "uuid",
  "keywords": [
    { "term": "seo tools", "keyword_group": "SEO" },
    { "term": "keyword research", "volume": 5000, "difficulty": 30 }
  ],
  "enrich": true
}
FieldTypeRequiredDescription
keywordsarrayYesArray of keyword objects
keywords[].termstringYesThe keyword term
keywords[].keyword_groupstringNoGroup name (auto-created if new)
keywords[].volumeintegerNoSearch volume (auto-filled if enrich: true)
keywords[].difficultyintegerNoKeyword difficulty
keywords[].cpcnumberNoCost per click
keywords[].intentstringNoSearch intent
enrichbooleanNoAuto-enrich keywords with volume/difficulty data

​
Response (201)

{
  "data": [{ "id": "uuid", "term": "seo tools", "volume": 12000 }],
  "count": 2
}

​
Delete keywords

DELETE /keywords

​
Request body

{
  "website_id": "uuid",
  "ids": ["uuid1", "uuid2"]
}

​
Response

{ "success": true, "deleted": 2 }

​
Toggle keyword star

PATCH /keywords/:id/star

​
Request body

{ "is_starred": true }

​
Response

{ "success": true, "is_starred": true }

​
Bulk update status

PATCH /keywords/status

​
Request body

{
  "ids": ["uuid1", "uuid2"],
  "status": "planned"
}

​
Response

{ "success": true, "updated": 2 }

​
Trigger keyword research

POST /keywords/research

​
Request body

{
  "website_id": "uuid",
  "seed_keywords": ["seo tools", "content marketing"],
  "language": "en",
  "country": "US"
}

​
Response

{
  "data": {
    "keywords": [],
    "clusters": []
  }
}

​
List keyword groups

GET /keywords/groups
ParameterTypeDescription
website_idUUIDTarget website

​
Response

{
  "data": [
    { "id": "uuid", "name": "SEO Tools", "website_id": "uuid", "created_at": "2024-01-15T10:00:00Z" }
  ]
}