API 레퍼런스

기본 URL

https://storelift.net/v1

아래의 모든 경로는 이 주소를 기준으로 합니다. 조회에는 GET을 보내고, POST는 /actions에서만 씁니다.

인증

키는 Authorization: Bearer <key> 또는 x-api-key에 넣어 보냅니다. 키는 설정 › API에서 만들며, 키마다 스코프, 선택 사항인 IP 허용 목록, 선택 사항인 앱 목록, 선택 사항인 월간 크레딧 예산을 가집니다. 예산에 도달한 키는 달이 바뀔 때까지 402 key_budget_reached로 응답하고, 다른 키는 계속 작동합니다.

REST API용 라이브 키(sl_live_)는 Pro 이상에서, 또는 어느 요금제에서든 크레딧 팩이 있으면 쓸 수 있습니다. Free에는 MCP 서버에서만 작동하는 라이브 키 1개가 포함됩니다. 테스트 키(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."
  }
}

공통 매개변수

아래 매개변수는 이를 받는 모든 엔드포인트에서 같은 뜻으로 쓰이며, 엔드포인트마다 자신이 받는 매개변수를 나열합니다.