API reference

Base URL

https://storelift.net/v1

Every path below is relative to it. Send GET for reads and POST only on /actions.

Authentication

Send the key in Authorization: Bearer <key> or in x-api-key. Create keys under Settings › API; each key carries scopes, an optional IP allow list, an optional app list and an optional monthly credit budget. A key that reaches its budget answers 402 key_budget_reached until the month turns; the other keys keep working.

Live keys (sl_live_) for the REST API are on Pro and above, or on any plan with a credit pack. Free includes one live key that works on the MCP server only. Test keys (sl_test_) return the sandbox data on every plan. Assistants sign in over OAuth through the MCP server on every plan.

Credits and limits

Each call costs the credits listed on it; /account and /usage cost 0, and a write's preview costs 0. Every response carries x-credits-used, x-credits-limit, x-credits-remaining and x-credits-reset.

Requests per second are set per plan; past it you get 429 rate_limited with retry-after. Hive endpoints open with purchased API credits or with Hive Explorer and also count against a daily allowance: 500 calls on pack credits, 10,000 with Hive Explorer. Credits per call

Sandbox

https://storelift.net/v1/sandbox answers every read below that has a sample response, with no key and no credits. The data is fixed and dated, so tests stay stable.

Test keys (sl_test_) return the same data on the live base URL and never write.

Reading a rank

A rank has three states and they stay distinct: measured: false means the query was not measured that day, rank: null means it was measured and the app is outside the results read, and a number is the rank.

Errors

Every error has the same body: { "error": "<code>", "message": "…", "docs": "…" }. error is stable; branch on it, not on message. Some codes add fields such as scope, field or limit. All error codes

Worked examples

Three jobs, from the first call to the result you keep. Every command runs against the sandbox, so it spends no credits and changes nothing, and each response is what the sandbox returns for it.

With your own key the paths are the same without /sandbox and each call costs the credits listed on it. A test key (sl_test_) answers with the sandbox data there too, at 0 credits.

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."
  }
}

Common parameters

These read the same on every endpoint that takes them; each endpoint lists the ones it takes.