API documentation

Knockplum is a credit-metered REST API (with an MCP wrapper) for live App Store and Google Play data. Base URL when live:

https://api.knockplum.com

Overview

All endpoints return JSON with the data you asked for. Credits are deducted only on successful responses.

Authentication

Send your API key as a Bearer token. Keys look like kp_live_… after launch (and kp_test_… in sandbox).

curl https://api.knockplum.com/v1/ios/app \
  -H "Authorization: Bearer kp_live_xxxxxxxx" \
  -H "Accept: application/json" \
  -G --data-urlencode "app_id=284882215" \
  --data-urlencode "country=us"

Credits

$1 = 100 credits ($0.01 per credit). Pre-order founding pack: $19 = 2,000 credits. Free grant: 30 credits on signup. Credits stay on your balance until spent.

Call type	Credits	USD
Lookups (metadata, category ranking)	2	$0.02
Search / volume / featuring / suggest	10	$0.10

Failed auth or validation errors do not spend credits. Upstream store timeouts may be retried; see error codes below.

Endpoints

Live coverage at launch. Query parameters are shown in each example.

GET

Category ranking

2 credits

/v1/ios/charts

Live chart position for any app, category, and country.

Example request

GET /v1/ios/charts?app_id=284882215&country=us&chart=free

curl "https://api.knockplum.com/v1/ios/charts?app_id=284882215&country=us&chart=free" \
  -H "Authorization: Bearer kp_live_xxxxxxxx"

Example response — 200

{
  "app_id": "284882215",
  "country": "us",
  "category": "Social Networking",
  "chart": "free",
  "rank": 14,
  "fetched_at": "2026-08-11T09:24:03Z"
}

GET

App metadata

2 credits

/v1/ios/app

Title, subtitle, description, screenshots, version, ratings.

Example request

GET /v1/ios/app?app_id=284882215&country=us

Example response — 200

{
  "app_id": "284882215",
  "title": "Facebook",
  "subtitle": "Connect with friends",
  "developer": "Meta Platforms, Inc.",
  "rating": 4.2,
  "rating_count": 12800421,
  "version": "512.0"
}

GET

Search results

10 credits

/v1/ios/search

Live App Store search results for a keyword, in ranked order.

Example request

GET /v1/ios/search?term=habit%20tracker&country=us&limit=10

Example response — 200

{
  "term": "habit tracker",
  "country": "us",
  "results": [
    { "rank": 1, "app_id": "1312014438", "title": "Habit Tracker" },
    { "rank": 2, "app_id": "1119985622", "title": "Productive" }
  ]
}

GET

Search volume

10 credits

/v1/ios/keyword

Search popularity for a keyword, including Apple-sourced scores when available.

Example request

GET /v1/ios/keyword?term=budget%20planner&country=us

Example response — 200

{
  "term": "budget planner",
  "country": "us",
  "popularity": 51,
  "popularity_source": "apple"
}

GET

Featuring

10 credits

/v1/ios/featured

Editorial and featuring placements on the App Store today.

Example request

GET /v1/ios/featured?country=us&category=games

Example response — 200

{
  "ok": true,
  "data": { "...": "endpoint-specific payload" },
  "fetched_at": "2026-08-11T09:24:03Z"
}

GET

Autocomplete suggestions

10 credits

/v1/suggest

Real store autocomplete — the phrases people actually type.

Example request

GET /v1/suggest?country=us&term=photo%20editor

Example response — 200

{
  "ok": true,
  "data": { "...": "endpoint-specific payload" },
  "fetched_at": "2026-08-11T09:24:03Z"
}

GET

Category ranking

2 credits

/v1/play/charts

Top-chart position by category and country on Google Play.

Example request

GET /v1/play/charts?country=us&app_id=com.spotify.music

Example response — 200

{
  "ok": true,
  "data": { "...": "endpoint-specific payload" },
  "fetched_at": "2026-08-11T09:24:03Z"
}

GET

App metadata

2 credits

/v1/play/app

Listing text, installs band, ratings, developer, last update.

Example request

GET /v1/play/app?country=us&app_id=com.spotify.music

Example response — 200

{
  "ok": true,
  "data": { "...": "endpoint-specific payload" },
  "fetched_at": "2026-08-11T09:24:03Z"
}

GET

Search results

10 credits

/v1/play/search

Live Google Play search results for a keyword.

Example request

GET /v1/play/search?country=us&term=photo%20editor

Example response — 200

{
  "ok": true,
  "data": { "...": "endpoint-specific payload" },
  "fetched_at": "2026-08-11T09:24:03Z"
}

Errors

Errors always return a JSON body with error, code, and message. HTTP status matches the class of failure.

HTTP	code	When	Credits
400	bad_request	Missing or invalid params	0
401	unauthorized	Missing or invalid API key	0
402	insufficient_credits	Balance too low for the call	0
404	not_found	App / keyword not found	0*
429	rate_limited	Too many requests	0
502	upstream_error	Store upstream failed	0

* Validated empty results (e.g. a real keyword with zero hits) may still charge as a successful search; true not-found for a bad app id does not.

Example error — 402

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": true,
  "code": "insufficient_credits",
  "message": "This call costs 10 credits; your balance is 4.",
  "credits_required": 10,
  "credits_remaining": 4,
  "request_id": "req_01J9XK..."
}

Example error — 401

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": true,
  "code": "unauthorized",
  "message": "Missing or invalid Authorization Bearer token.",
  "request_id": "req_01J9XL..."
}

Example error — 400

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": true,
  "code": "bad_request",
  "message": "Query parameter \"app_id\" is required.",
  "details": {
    "param": "app_id",
    "reason": "required"
  },
  "request_id": "req_01J9XM..."
}

MCP

The MCP server wraps the same endpoints and credit ledger. One key, one balance.

{
  "mcpServers": {
    "knockplum": {
      "command": "npx",
      "args": ["-y", "@knockplum/mcp"],
      "env": {
        "KNOCKPLUM_API_KEY": "kp_live_xxxxxxxx"
      }
    }
  }
}

Docs reflect the planned launch contract. Minor field names may tighten before GA — founding buyers get a changelog email.