KDPTop API and AI integration

KDPTop exposes the Amazon Books / Kindle eBooks category trees we continuously crawl, Best Sellers / New Releases / Top 100 Free list snapshots, per-book rank history, and category opportunity metrics as REST API and MCP (Model Context Protocol) endpoints. Programs, ChatGPT, Grok, Claude, Cursor, and more can query this data directly.

Authentication

In the Developer Center create an API key (formatted like kdp_xxx, shown only once, so store it safely). When calling, use either method to pass it:

Authorization: Bearer kdp_your_key     # recommended
X-API-Key: kdp_your_key
?key=kdp_your_key                       # only for clients that can't set headers

?key= This method is only for clients that can't set custom request headers (such as some MCP connectors). The key appears in the URL, so use it only with trusted clients and revoke it in the Developer Center immediately if leaked.

Quotas and error codes

REST and MCP share the account's daily call quota (each request / each tool call counts as 1), and the history data range depends on your plan.

REST responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers; over MCP, the AI is told in the result when less than 10% is left. Call /usage or get_usage any time to check usage; it doesn't count as a call.

REST endpoints

Base URL:https://kdptop.com/api/v1. Returns JSON; everything is GET unless marked POST. Interactive docs: /api/v1/docs

Example

# Search categories in Chinese
curl "https://kdptop.com/api/v1/categories/search?q=cozy mystery&store=kindle" \
  -H "Authorization: Bearer kdp_your_key"

# Top 20 Kindle Best Sellers in a category
curl "https://kdptop.com/api/v1/lists/154606011/best?limit=20" \
  -H "Authorization: Bearer kdp_your_key"

# Kindle leaf category opportunities with median reviews < 200 and price >= $3.99
curl "https://kdptop.com/api/v1/opportunities?store=kindle&leaf_only=true&max_median_reviews=200&min_median_price=3.99" \
  -H "Authorization: Bearer kdp_your_key"

Field descriptions

• node_id: Amazon category node ID;store:books Print / kindle eBook
• list_type:best Best Sellers,new New Releases,free Top 100 Free (Kindle only)
• opportunity_score: 0-100; higher means a lower review barrier, faster turnover, and easier entry for new books
• median_reviews / median_price: median review count / price (USD) of books on the list;top100_turnover: share of the list that turned over versus the previous day
• new_release_ratio: share of new books appearing for the first time within 90 days;prev_rank: rank in the previous day's snapshot

MCP endpoint

at https://kdptop.com/api/mcp, implementing MCP Streamable HTTP (stateless, JSON responses, protocol versions 2025-06-18 / 2025-03-26 / 2024-11-05). initialize and tools/list No authentication required,tools/call requires an API key. All tools are read-only except follow:

Built-in prompts

Clients that support prompts (Claude, Cursor and others) can pick these workflows directly:

Connect to ChatGPT

Option 1: Custom GPT (GPT Actions)

1. ChatGPT → Explore GPTs → Create → Configure → Create new action.
2. Choose "Import from URL" and enter https://kdptop.com/api/v1/openapi.json.
3. For authentication, select API Key, type Bearer, and paste your kdp_ key.
4. Set the privacy policy URL to https://kdptop.com/, and in the instructions write "Call KDPTop when Amazon KDP data is needed."

You are an Amazon KDP research assistant. For questions about topics, categories, competitors, pricing or authors, call KDPTop first:
1. Find the category or writing direction with searchCategories or listDirections, and read the verdict and reasons with getDecisionCard;
2. Read the Top list with getList (it already includes est. sales, BSR, publication date and author_key, so there's no need to look books up one by one);
3. Use getBreakouts to see who just broke in, use author_track to tell one-off hits from authors who keep producing hits, then dig deeper with getAuthorTimeline and compareAuthors;
4. When citing data, give the capture time captured_at and the Amazon link; before many calls, check the remaining quota with getUsage.

Option 2: Connectors / Apps (MCP)

In ChatGPT settings → Apps & Connectors → Advanced settings, enable developer mode → Create connector, and set the MCP server URL to:

https://kdptop.com/api/mcp

Choose OAuth for authentication, save, and click Allow on the KDPTop authorization page; no key to copy (dynamic client registration and PKCE supported). We implement the search / fetch tools required by ChatGPT, usable for deep research.

Option 3: OpenAI Responses API

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Which mystery subcategories on Kindle have the lowest review barrier?",
    "tools": [{
      "type": "mcp",
      "server_label": "kdpdata",
      "server_url": "https://kdptop.com/api/mcp",
      "headers": { "Authorization": "Bearer kdp_your_key" },
      "require_approval": "never"
    }]
  }'

Connect to Grok (xAI)

xAI Responses API (remote MCP)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Use KDPTop to find the 5 subcategories with the highest opportunity score under Kindle romance categories",
    "tools": [{
      "type": "mcp",
      "server_label": "kdpdata",
      "server_description": "Amazon KDP bestseller lists, categories and niche metrics",
      "server_url": "https://kdptop.com/api/mcp",
      "authorization": "Bearer kdp_your_key"
    }]
  }'

authorization value is sent as-is in the Authorization header and must include the Bearer prefix. You can use allowed_tools to limit tools.

xAI Python SDK

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client()  # reads XAI_API_KEY
chat = client.chat.create(
    model="grok-4.7",
    tools=[mcp(server_url="https://kdptop.com/api/mcp", server_label="kdpdata",
               authorization="Bearer kdp_your_key")],
)
chat.append(user("Which new cozy mystery books broke into Best Sellers in the last 30 days?"))
print(chat.sample().content)

Grok CLI

grok mcp add --transport http kdpdata https://kdptop.com/api/mcp --header "Authorization: Bearer kdp_your_key"

Connect to Claude / Cursor / other MCP clients

Clients that support remote MCP can simply add the server. Cursor (~/.cursor/mcp.json) / Claude Code, etc.:

{
  "mcpServers": {
    "kdptop": {
      "url": "https://kdptop.com/api/mcp",
      "headers": { "Authorization": "Bearer kdp_your_key" }
    }
  }
}

Claude Code command line:

claude mcp add --transport http kdptop https://kdptop.com/api/mcp --header "Authorization: Bearer kdp_your_key"

Claude Desktop (needs Node.js; add to claude_desktop_config.json):

{
  "mcpServers": {
    "kdptop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://kdptop.com/api/mcp", "--header", "Authorization: Bearer kdp_your_key"]
    }
  }
}

Claude.ai / Claude Desktop custom connector: Settings → Connectors → Add custom connector, URL https://kdptop.com/api/mcp, then click Connect and sign in with your KDPTop account (OAuth); no key needed.

Clients that only take a URL and don't support OAuth can use https://kdptop.com/api/mcp?key=kdp_your_key.

llms.txt

We provide https://kdptop.com/llms.txt site documentation for LLMs (data scope, endpoints, authentication), which you can paste directly to an AI as context.