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

​
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[].term (or keyword)stringYesThe keyword term
keywords[].keyword_group (or group)stringNoGroup name (auto-created if new)
keywords[].volumeintegerNoSearch volume (auto-filled if enrich: true)
keywords[].difficultyintegerNoKeyword difficulty
keywords[].cpcnumberNoCost per click
keywords[].intentstringNoSearch intent
keywords[].opportunitystringNoOpportunity level (High, Medium, Low)
keywords[].funnel_stagestringNoFunnel stage (awareness, consideration, decision)
keywords[].languagestringNoLanguage code
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
Generates keyword ideas using AI + DataForSEO enrichment. Long-running — returns a job handle by default. Pass "sync": true to wait inline (not recommended; subject to gateway timeouts).

​
Request body

{
  "website_id": "uuid",
  "seed_keywords": ["seo tools", "content marketing"],
  "language": "en",
  "country": "US",
  "sync": false
}
FieldTypeRequiredDescription
seed_keywordsarrayYesSeed terms to expand from
languagestringNoLanguage code (e.g. en)
countrystringNoCountry code (e.g. US)
syncbooleanNotrue to wait for inline result (not recommended)

​
Response (202 Accepted)

{
  "data": {
    "job_id": "abc-uuid",
    "status": "pending",
    "poll_url": "/keywords/research/abc-uuid"
  }
}

​
Poll a research job

GET /keywords/research/:jobId

​
Response

{
  "data": {
    "id": "abc-uuid",
    "status": "completed",
    "result": { "keywords": [ ] },
    "error": null,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:01:30Z"
  }
}
status is one of pending, processing, completed, or failed.

​
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" }
  ]
}