API-Referenz

Basis-URL

https://storelift.net/v1

Jeder Pfad unten ist relativ dazu. Senden Sie GET für Lesezugriffe und POST nur auf /actions.

Authentifizierung

Senden Sie den Schlüssel in Authorization: Bearer <key> oder in x-api-key. Schlüssel erstellen Sie unter Einstellungen › API; jeder Schlüssel trägt Scopes, eine optionale IP-Freigabeliste, eine optionale App-Liste und ein optionales monatliches Credit-Budget. Ein Schlüssel, der sein Budget erreicht, antwortet mit 402 key_budget_reached, bis der Monat wechselt; die anderen Schlüssel funktionieren weiter.

Live-Schlüssel (sl_live_) für die REST-API gibt es ab Pro oder in jedem Plan mit einem Credit-Paket. Free enthält einen Live-Schlüssel, der nur am MCP-Server funktioniert. Testschlüssel (sl_test_) liefern in jedem Plan die Sandbox-Daten. Assistenten melden sich in jedem Plan per OAuth über den MCP-Server an.

Credits und Limits

Jeder Aufruf kostet die Credits, die bei ihm angegeben sind; /account und /usage kosten 0, und die Vorschau eines Schreibvorgangs kostet 0. Jede Antwort enthält x-credits-used, x-credits-limit, x-credits-remaining und x-credits-reset.

Die Anfragen pro Sekunde sind je Plan festgelegt; darüber erhalten Sie 429 rate_limited mit retry-after. Hive-Endpunkte öffnen sich mit gekauften API-Credits oder mit Hive Explorer und zählen zusätzlich gegen eine Tagesgrenze: 500 Aufrufe mit Paket-Credits, 10.000 mit Hive Explorer. Credits pro Aufruf

Sandbox

https://storelift.net/v1/sandbox beantwortet jeden Lesezugriff unten, der eine Beispielantwort hat, ohne Schlüssel und ohne Credits. Die Daten sind fest und datiert, damit Tests stabil bleiben.

Testschlüssel (sl_test_) liefern dieselben Daten auf der Live-Basis-URL und schreiben nie.

Einen Rang lesen

Ein Rang hat drei Zustände, und sie bleiben getrennt: measured: false heißt, die Suchanfrage wurde an diesem Tag nicht gemessen; rank: null heißt, sie wurde gemessen und die App steht außerhalb der gelesenen Ergebnisse; eine Zahl ist der Rang.

Fehler

Jeder Fehler hat denselben Body: { "error": "<code>", "message": "…", "docs": "…" }. error ist stabil; verzweigen Sie danach, nicht nach message. Manche Codes ergänzen Felder wie scope, field oder limit. Alle Fehlercodes

Praxisbeispiele

Drei Aufgaben, vom ersten Aufruf bis zum Ergebnis, das Sie behalten. Jeder Befehl läuft gegen die Sandbox, verbraucht also keine Credits und ändert nichts, und jede Antwort ist die, die die Sandbox dafür zurückgibt.

Mit Ihrem eigenen Schlüssel sind die Pfade dieselben ohne /sandbox, und jeder Aufruf kostet die bei ihm angegebenen Credits. Ein Testschlüssel (sl_test_) antwortet auch dort mit den Sandbox-Daten, für 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."
  }
}

Gemeinsame Parameter

Diese bedeuten bei jedem Endpunkt, der sie annimmt, dasselbe; jeder Endpunkt führt auf, welche er annimmt.