Skip to main content
SmartKDP
Log inTry free tool
Log in

The KDP Keyword Generator API

Programmatic access to what the web tool shows — seven backend keyword boxes packed from your book and your market, every estimate a labelled range, every refusal typed.

Authentication

Every request carries Authorization: Bearer <token>. The token is your SmartKDP session token (signed-in web), or a device token minted from your account with a connect code — the same way the browser extension connects. Device tokens are listed and revocable from your account's device list. There are no separate API keys; if your team needs standing credentials, a device token is the supported path.

Saved sets and CSV downloads need the Research Suite. Starting a run never answers 402: without the suite the run takes the free shape — the seven boxes from your book and Amazon's own suggestions, with no market ranking — and the response says so with paid: false.

Endpoints

  • POST /research/backend-keywords

    Start a market check. Send mode (text, asin or project), marketplace, a listing or an asin (plus up to 3 competitors), a strategy (coverage, phrase_intact or themed), pinned and excluded phrases, and an idempotency_key. Answers 202 with {run_id, paid, stream}. The same key with the same body answers the same run; the same key with another body is 409 idempotency_key_reused.

  • GET /research/backend-keywords/{run_id}/events

    The run as it happens (server-sent events): meta, candidate, evidence, progress, pack, rerank, summary, done, error. Send Last-Event-ID to resume from the last event you received.

  • GET /research/backend-keywords/runs?cursor=&limit=

    Your run history, newest first (Research Suite).

  • GET /research/backend-keywords/runs/{run_id}?format=json|csv

    One saved run. The saved pack never changes; served is today's pack beside it when the engine has moved on. format=csv (Research Suite) is one file whose record_type column names each row: box, alternate, exclusion, token or uncovered.

  • DELETE /research/backend-keywords/runs/{run_id}

    Take a run out of your history.

  • GET | POST /research/backend-keywords/sets

    Your named sets of up to seven phrases: list them, or create one (Research Suite).

  • GET | PATCH | DELETE /research/backend-keywords/sets/{set_id}

    Read, rename or rewrite, or delete one set. PATCH carries If-Match: <version>, so two edits never silently overwrite each other.

  • POST /projects/{project_id}/listing/keywords/apply-set

    {set_id, strategy?}: packs the book's boxes with the set pinned and stores the result for Listing Studio.

The vocabulary is the contract

A pack is the seven boxes, the alternates that nearly made it, the exclusions — each with one reason from a closed list, never a free-text judgement — and the coverage of your book's words. modeled is the Research Suite's re-ranked pack: every box carries an estimate as a band [low, high] with a confidence badge — never a bare number — because Amazon publishes no search volume and a single figure would be a guess dressed as a fact.

served is today's engine beside the saved pack: a saved run is immutable, so when the packing has moved on since, the run resource carries both and you can show the difference rather than replace what the author saw. partial and stop_reason: complete | deadline | blocked say how a run ended — one that ran out of time, or could not read Amazon, says so and ships what it has rather than rendering a thin result as a complete one. evidence_summary names which sources answered, and its degraded list names the ones that did not.

Strategies

  • coverage — the most distinct words from your book covered across the seven boxes.
  • phrase_intact — phrases shoppers typed, exactly as shown, come first.
  • themed — each box takes a different angle: theme, audience, format, problem, occasion, feature, level.

Stores

marketplace is one of amazon.com, amazon.co.uk, amazon.de, amazon.fr, amazon.es, amazon.it, amazon.com.br. amazon.co.jp is refused as unsupported_tokenizer. On amazon.fr, amazon.es, amazon.it and amazon.com.br the asin mode and competitors are not available yet and answer 422.

Refusals

Refusals are typed. 401 for a missing or revoked token. 404 for a run or set that is not yours — it is indistinguishable from one that does not exist. 409 with idempotency_key_reused, bk_runs_in_flight (two runs already live), name_taken and stale_version for sets, and sets_full once you hold 200 sets. 422 as keywords_refused {code} when the market check cannot pack this book, or with field errors for a malformed body. 429 with {scope, retry_after_secs} for a rate window. 503 when the market check is unavailable — try again later; nothing was recorded.

Read the generator's FAQ for what each box shows, what is set aside and why, and how to read Amazon's suggestions.