{"openapi":"3.1.0","info":{"title":"KDP Intelligence API","description":"Niche demand + competition intelligence for Kindle Direct Publishing authors.\n\n## Payment\nPaid endpoints require an `X-Payment` header containing a base64-encoded [x402](https://github.com/coinbase/x402) USDC authorization on Base.\n\n### Tiered Pricing\n| Query Type | Price |\n|---|---|\n| Cached/pre-seeded keyword | **$0.03 USDC** |\n| Live on-demand research (new keyword) | **$0.10 USDC** |\n\nUse `GET /v1/niche/{keyword}/check` (free) to check availability and pricing before paying.\n\n## Agent Usage\n1. Call `GET /v1/niches` (free) to discover available keywords.\n2. Call `GET /v1/niche/{keyword}/check` (free) to verify availability and pricing tier.\n3. For each keyword of interest, call `GET /v1/niche/{keyword}` with a valid `X-Payment` header to retrieve full intelligence data.\n4. On HTTP 402, parse the response body `accepts[0]` fields to construct payment.","version":"0.2.0","x-payment-required":{"description":"This API uses the x402 payment protocol with tiered pricing. Cached keywords cost $0.03 USDC; live research costs $0.10 USDC. Use GET /v1/niche/{keyword}/check (free) to determine the tier before paying.","production":{"version":1,"accepts":[{"scheme":"exact","network":"base-mainnet","maxAmountRequired":"100000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","extra":{"name":"USD Coin","version":"2"}}]},"staging":{"version":1,"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"100000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","extra":{"name":"USD Coin","version":"2"}}]},"pricingTiers":{"cached":{"costUSDC":0.03,"amountUnits":30000},"live":{"costUSDC":0.1,"amountUnits":100000}},"paymentHeader":"X-Payment","paymentScheme":"x402","docs":"https://github.com/coinbase/x402"}},"paths":{"/v1/niche/{keyword}/check":{"get":{"tags":["niches"],"summary":"Check niche data availability and pricing tier (free, no payment required)","description":"Free endpoint to check whether niche data exists before paying.\n\nReturns availability status, staleness, and the pricing tier:\n- **$0.03 USDC** for cached/pre-seeded keywords\n- **$0.10 USDC** for live on-demand research (new keywords)","operationId":"check_niche_availability_v1_niche__keyword__check_get","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\w\\s\\-]+$","description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)","title":"Keyword"},"description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheAvailability"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/niche/{keyword}":{"get":{"tags":["niches"],"summary":"Get KDP niche intelligence","description":"Return demand, competition, BSR, revenue, and pricing intelligence for a KDP niche keyword.\n\nRequires X-Payment header: x402 USDC authorization on Base.\n\n**Tiered pricing:**\n- **$0.03 USDC** — cached/pre-seeded keywords (instant response)\n- **$0.10 USDC** — live on-demand research for new/stale keywords (up to 60s)\n\nUse `GET /v1/niche/{keyword}/check` (free) to check availability and pricing\nbefore paying.","operationId":"get_niche_v1_niche__keyword__get","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\w\\s\\-]+$","description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)","title":"Keyword"},"description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheResponse"}}}},"402":{"description":"Payment required — include X-Payment header with x402 USDC authorization","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","example":1},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base-mainnet"},"maxAmountRequired":{"type":"string","description":"30000 for cached ($0.03) or 100000 for live ($0.10)"},"payTo":{"type":"string"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}},"error":{"type":"string"}}},"example":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base-mainnet","maxAmountRequired":"30000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}],"error":"Payment required — include X-Payment header with EIP-3009 authorization"}}}},"503":{"description":"Live research pipeline unavailable — use /v1/niches for pre-seeded data"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-required":true,"x-payment-tiers":{"cached":{"amount_usdc":0.03,"description":"Cached/pre-seeded keyword"},"live":{"amount_usdc":0.1,"description":"Live on-demand research"}},"x-payment-network":"base-mainnet","x-payment-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-payment-scheme":"exact"}},"/v1/preview/{keyword}":{"get":{"tags":["niches"],"summary":"Free preview — demand score only, no payment required","description":"Free, zero-friction preview of a KDP niche keyword.\n\nReturns just the headline demand score plus a CTA to the paid endpoint.\nDesigned as a low-stakes touchpoint for crawlers, AI agents, and humans\nevaluating whether to pay for the full intelligence (competition,\nBSR ranges, revenue estimates, review thresholds, pricing).\n\nNo payment required.","operationId":"preview_niche_v1_preview__keyword__get","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\w\\s\\-]+$","description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)","title":"Keyword"},"description":"KDP niche keyword (letters, digits, spaces, dashes; 1–80 chars)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NichePreview"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/niches":{"get":{"tags":["niches"],"summary":"List all available KDP niches","description":"Discover all available KDP niche keywords, ordered by demand score descending.","operationId":"list_niches_v1_niches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Results per page","default":20,"title":"Limit"},"description":"Results per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NichesListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NicheAvailability":{"properties":{"keyword":{"type":"string","title":"Keyword"},"available":{"type":"boolean","title":"Available","description":"Whether cached data exists for this keyword"},"stale":{"type":"boolean","title":"Stale","description":"Whether cached data is older than 7 days","default":false},"message":{"type":"string","title":"Message"},"query_cost_usdc":{"type":"number","title":"Query Cost Usdc","description":"Cost in USDC: $0.03 for cached keywords, $0.10 for live research"},"api_version":{"type":"string","title":"Api Version","default":"0.1.0"}},"type":"object","required":["keyword","available","message","query_cost_usdc"],"title":"NicheAvailability"},"NichePreview":{"properties":{"keyword":{"type":"string","title":"Keyword"},"demand_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Demand Score"},"monthly_searches":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Searches"},"available":{"type":"boolean","title":"Available","description":"Whether full data is cached and ready to fetch"},"full_data_cost_usdc":{"type":"number","title":"Full Data Cost Usdc","description":"Cost of the full /v1/niche/{keyword} call"},"full_data_url":{"type":"string","title":"Full Data Url","description":"URL to fetch the full intelligence (paid via x402)"},"api_version":{"type":"string","title":"Api Version","default":"0.1.0"}},"type":"object","required":["keyword","demand_score","available","full_data_cost_usdc","full_data_url"],"title":"NichePreview"},"NicheResponse":{"properties":{"keyword":{"type":"string","title":"Keyword","description":"Normalized niche keyword"},"demand_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Demand Score","description":"Keyword demand score (0–100)"},"competition_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Competition Score","description":"Competition intensity (0–100)"},"bsr_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bsr Range","description":"Amazon BSR range, e.g. '1,000–5,000'"},"monthly_revenue_estimate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Revenue Estimate","description":"Estimated monthly revenue (USD)"},"review_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Review Threshold","description":"Min review count to rank competitively"},"pricing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pricing","description":"Average book price (USD)"},"data_freshness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Freshness","description":"ISO 8601 timestamp of last data refresh"},"data_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Source","description":"Data source (e.g. 'dataforseo+brightdata')"},"data_quality":{"type":"string","title":"Data Quality","description":"Data quality: 'full' (all sources), 'partial' (some sources failed), or 'cached' (pre-seeded)","default":"full"},"cache_status":{"type":"string","title":"Cache Status","description":"'cached' if served from cache/DB, 'live' if fresh research was performed","default":"live"},"cache_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cache Expires At","description":"ISO 8601 timestamp when cached data expires"},"query_cost_usdc":{"type":"number","title":"Query Cost Usdc","description":"Per-query cost in USDC","default":0.03},"api_version":{"type":"string","title":"Api Version","description":"API version","default":"0.1.0"}},"type":"object","required":["keyword","demand_score","competition_score"],"title":"NicheResponse"},"NichesListResponse":{"properties":{"niches":{"items":{"$ref":"#/components/schemas/NicheResponse"},"type":"array","title":"Niches"},"total":{"type":"integer","title":"Total"},"api_version":{"type":"string","title":"Api Version","default":"0.1.0"}},"type":"object","required":["niches","total"],"title":"NichesListResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}