API 参考

基础 URL

https://storelift.net/v1

下面的每个路径都相对于它。读取用 GET，只有 /actions 用 POST。

身份验证

在 Authorization: Bearer <key> 或 x-api-key 中发送密钥。在“设置 › API”里创建密钥；每个密钥都带有权限范围，并可选设置 IP 白名单、应用列表和每月额度预算。达到预算的密钥会一直返回 402 key_budget_reached，直到进入下个月；其他密钥照常工作。

用于 REST API 的正式密钥（sl_live_）在 Pro 及以上套餐提供，任何套餐购买额度包后也可使用。Free 套餐包含一个仅适用于 MCP 服务器的正式密钥。测试密钥（sl_test_）在任何套餐下都返回沙盒数据。AI 助手在任何套餐下都通过 MCP 服务器以 OAuth 登录。

额度与限制

每次调用消耗的额度都标在该接口上；/account 和 /usage 消耗 0 额度，写入的预览也消耗 0 额度。每个响应都带有 x-credits-used、x-credits-limit、x-credits-remaining 和 x-credits-reset。

每秒请求数按套餐设定；超过后会收到 429 rate_limited 和 retry-after。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."
  }
}

通用参数

在接受这些参数的每个接口上，它们的含义都相同；每个接口会列出自己接受的参数。