Référence de l'API

URL de base

https://storelift.net/v1

Tous les chemins ci-dessous sont relatifs à cette URL. Envoyez GET pour les lectures et POST uniquement sur /actions.

Authentification

Envoyez la clé dans Authorization: Bearer <key> ou dans x-api-key. Créez les clés sous Réglages › API ; chaque clé porte des scopes, une liste facultative d'adresses IP autorisées, une liste facultative d'apps et un budget mensuel de crédits facultatif. Une clé qui atteint son budget répond 402 key_budget_reached jusqu'au changement de mois ; les autres clés continuent de fonctionner.

Les clés live (sl_live_) pour l'API REST sont disponibles à partir de Pro, ou sur n'importe quel plan avec un pack de crédits. Free inclut une clé live qui ne fonctionne qu'avec le serveur MCP. Les clés de test (sl_test_) renvoient les données de la sandbox sur tous les plans. Les assistants se connectent via OAuth par le serveur MCP sur tous les plans.

Crédits et limites

Chaque appel coûte le nombre de crédits indiqué pour lui ; /account et /usage coûtent 0, et l'aperçu d'une écriture coûte 0. Chaque réponse porte x-credits-used, x-credits-limit, x-credits-remaining et x-credits-reset.

Le nombre de requêtes par seconde est fixé par plan ; au-delà, vous recevez 429 rate_limited avec retry-after. Les endpoints Hive s'ouvrent avec des crédits API achetés ou avec Hive Explorer et sont aussi décomptés d'un quota quotidien : 500 appels avec les crédits d'un pack, 10 000 avec Hive Explorer. Crédits par appel

Sandbox

https://storelift.net/v1/sandbox répond à toutes les lectures ci-dessous qui ont un exemple de réponse, sans clé et sans crédits. Les données sont fixes et datées, ce qui garde les tests stables.

Les clés de test (sl_test_) renvoient les mêmes données sur l'URL de base live et n'écrivent jamais.

Lire un rang

Un rang a trois états, et ils restent distincts : measured: false signifie que la requête n'a pas été mesurée ce jour-là, rank: null qu'elle a été mesurée et que l'app est en dehors des résultats lus, et un nombre est le rang.

Erreurs

Toutes les erreurs ont le même corps : { "error": "<code>", "message": "…", "docs": "…" }. error est stable ; branchez votre logique sur ce champ, pas sur message. Certains codes ajoutent des champs tels que scope, field ou limit. Tous les codes d'erreur

Exemples commentés

Trois tâches, du premier appel au résultat que vous conservez. Chaque commande s'exécute sur la sandbox : elle ne dépense donc aucun crédit et ne change rien, et chaque réponse est celle que la sandbox renvoie pour cette commande.

Avec votre propre clé, les chemins sont les mêmes sans /sandbox et chaque appel coûte le nombre de crédits indiqué pour lui. Une clé de test (sl_test_) y répond aussi avec les données de la sandbox, pour 0 crédit.

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

Paramètres communs

Ils se lisent de la même façon sur tous les endpoints qui les acceptent ; chaque endpoint indique ceux qu'il accepte.