API リファレンス

ベース URL

https://storelift.net/v1

以下のパスはすべて、このベース URL からの相対パスです。読み取りには GET を送り、POST を送るのは /actions だけです。

認証

キーは Authorization: Bearer <key> または x-api-key で送ります。キーは 設定 › APIキー で作成します。キーごとにスコープを持ち、任意で IP 許可リスト、アプリのリスト、月間のクレジット予算を設定できます。予算に達したキーは、月が替わるまで 402 key_budget_reached を返します。ほかのキーは引き続き使えます。

REST API 用の本番キー（sl_live_）は、Pro 以上か、どのプランでもクレジットパックがあれば使えます。Free には、MCP サーバーでのみ使える本番キーが一つ含まれます。テストキー（sl_test_）は、どのプランでもサンドボックスのデータを返します。アシスタントは、どのプランでも MCP サーバー を通じて OAuth でサインインします。

クレジットと上限

各呼び出しは、そこに記載されたクレジットを消費します。/account と /usage は 0 で、書き込みのプレビューも 0 です。すべてのレスポンスに x-credits-used、x-credits-limit、x-credits-remaining、x-credits-reset が付きます。

毎秒のリクエスト数はプランごとに決まっています。それを超えると、retry-after 付きの 429 rate_limited が返ります。Hive のエンドポイントは、購入した API クレジットまたは Hive Explorer で使えるようになり、一日あたりの利用枠にも数えられます。パックのクレジットでは 500 回、Hive Explorer では 10,000 回です。呼び出しごとのクレジット

サンドボックス

https://storelift.net/v1/sandbox は、以下の読み取りのうちサンプルレスポンスがあるものすべてに、キーなし、クレジットなしで応答します。データは固定で日付が入っているため、テストが安定します。

テストキー（sl_test_）は、本番のベース URL でも同じデータを返し、書き込みは一切行いません。

順位の読み方

順位には三つの状態があり、それぞれ区別されます。measured: false はその日にクエリが計測されなかったこと、rank: null は計測されたもののアプリが読み取った結果の範囲に入っていないことを表し、数値であればそれが順位です。

エラー

すべてのエラーは同じ本文を持ちます：{ "error": "<code>", "message": "…", "docs": "…" }。error は安定しているので、分岐には message ではなくこちらを使ってください。コードによっては、scope、field、limit などのフィールドが加わります。すべてのエラーコード

実践例

三つの作業を、最初の呼び出しから手元に残す結果まで示します。コマンドはすべてサンドボックスに対して実行するため、クレジットを消費せず、何も変更しません。各レスポンスは、そのコマンドに対してサンドボックスが返す内容です。

自分のキーを使う場合、パスは /sandbox を除けば同じで、各呼び出しはそこに記載されたクレジットを消費します。テストキー（sl_test_）は、そこでもサンドボックスのデータを 0 クレジットで返します。

function weeklyRow(body) {
  const ranked = body.keywords.filter((k) => k.measured && k.rank !== null);
  const best = ranked.reduce((a, b) => (a && a.rank <= b.rank ? a : b), null);
  return {
    measuredAt: body.measuredAt,
    country: body.country,
    platform: body.platform,
    keywords: body.keywords.length,
    ranked: ranked.length,
    absent: body.keywords.filter((k) => k.measured && k.rank === null).length,
    notMeasured: body.keywords.filter((k) => !k.measured).length,
    best: best && { term: best.term, rank: best.rank },
  };
}

{
  "measuredAt": "2026-09-27T02:10:00.000Z",
  "country": "us",
  "platform": "ios",
  "keywords": 8,
  "ranked": 6,
  "absent": 2,
  "notMeasured": 0,
  "best": {
    "term": "nature sounds",
    "rank": 29
  }
}

curl "https://storelift.net/v1/sandbox/apps/sbx-unknown/keywords?country=us"

{
  "error": "not_found",
  "message": "No such app in this workspace.",
  "docs": "https://storelift.net/docs/api/errors#not_found"
}

function rivalsAhead(body) {
  return body.rivals.map((r) => ({
    name: r.name,
    ratings: r.ratings,
    aheadOn: r.terms.length,
    absentOn: r.terms.filter((t) => t.ourRank === null).length,
  }));
}

[
  {
    "name": "Calm Rain",
    "ratings": 57046,
    "aheadOn": 8,
    "absentOn": 2
  },
  {
    "name": "Noisli",
    "ratings": 16114,
    "aheadOn": 8,
    "absentOn": 2
  },
  {
    "name": "Deep Sleep Tones",
    "ratings": 64683,
    "aheadOn": 8,
    "absentOn": 2
  }
]

curl "https://storelift.net/mcp" \
  -H "Authorization: Bearer $STORELIFT_TEST_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"get_rivals","arguments":{"appId":"sbx-unknown","country":"us"}}}'

ERROR: No such app in this workspace.

function allowance(body) {
  return {
    plan: body.plan,
    auth: body.auth,
    scopes: body.scopes,
    apps: body.apps.map((a) => a.id),
    creditsLeft: body.credits.limit - body.credits.used,
    ratePerSecond: body.ratePerSecond,
  };
}

{
  "plan": "studio",
  "auth": "test_key",
  "scopes": [
    "apps:read",
    "reviews:read",
    "ai:read",
    "revenue:read",
    "hive:read",
    "hive:spy",
    "hive:estimate",
    "ads:read"
  ],
  "apps": [
    "sbx-lumen",
    "sbx-quill"
  ],
  "creditsLeft": 50000,
  "ratePerSecond": 10
}

curl "https://storelift.net/mcp" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

{
  "jsonrpc": "2.0",
  "id": 9,
  "error": {
    "code": -32001,
    "message": "No credentials were sent. Sign in with OAuth on any plan, or add Authorization: Bearer <your Storelift API key>. Live keys require Pro, Studio, Enterprise, or an eligible Free account with purchased API credits or active Explorer. Tool access still depends on plan, scopes and credits. Generate a key at Storelift → Settings → API keys."
  }
}

共通パラメータ

これらは、受け付けるすべてのエンドポイントで同じ意味を持ちます。各エンドポイントには、そのエンドポイントが受け付けるものを記載しています。