Storelift

Storelift › Guides › The Storelift API

AI layer

The Storelift API

Everything the dashboard shows is also a JSON endpoint. 33 GET endpoints read your tracked apps and the wider market, and POST /v1/actions previews a change that POST /v1/actions/confirm then applies — so a script, a spreadsheet job or a CI step reads the same numbers and acts on them. The API is included with Pro and Studio. The full reference is at /docs/api/ and the machine-readable spec at /openapi.json (OpenAPI 3.1); an assistant working with the same data usually wants the MCP server, which also starts on Pro.

Start free →Free plan: 1 app, 10 keywords in each of 2 storefronts, 14 days of history, no card, no end date. Pro is $29/mo.

By Updated: 10 min read

Keyword tracking · rank history, this week's moves and tracked keywords

Base address and authentication

The base is https://storelift.net/v1. Create a key under Settings → API; it is shown once and stored only as a hash, so a lost key is replaced rather than recovered.

Send it as x-api-key, or as a bearer token if your client only does Authorization headers:

Terminal
curl -s https://storelift.net/v1/apps \
  -H "x-api-key: sl_live_..."
Public API access follows the key’s entitlement. Pro, Studio and Enterprise qualify. Check the account and usage endpoints for the key’s actual plan, scopes and allowance.

The 33 endpoints

EndpointWhat it returns
GET /v1/appsThe apps this account tracks. Every other call starts here — the id comes from this one.
GET /v1/apps/{id}One app plus the latest run's snapshot.
GET /v1/apps/{id}/featuringEditorial cards, In-App Events and Apple's You Might Also Like shelf per country, with the dated history of featurings and new events. dedicated tells a story about the app from a collection it sits in.
GET /v1/apps/{id}/keywordsCurrent rank per tracked keyword in one storefront, with the measurement state and the depth searched.
GET /v1/apps/{id}/rivalsThe apps standing above you, each with the terms they beat you on and both positions.
GET /v1/apps/{id}/aiWhether an assistant names your app for your category, with the stored series. Requires Pro, Studio or Enterprise.
GET /v1/apps/{id}/historyThe rank series per keyword, trimmed to the plan's history window.
GET /v1/apps/{id}/pageYour own listing as the store serves it, both platforms, plus the dated changes detected on it.
GET /v1/apps/{id}/reviewsRecent reviews with the star summary, the count new in this run, and the Play side when measured. /reviews/search searches the full archive by text, stars, version and dates; /reviews/stats gives the distribution, the daily curve and the per-version breakdown.
GET /v1/apps/{id}/timelineDated listing changes — version, screenshots, events, featuring, keyword-field edits — each with the keyword rank movement around it.
GET /v1/apps/{id}/chartsTop-chart position for the app's genre and storefront, with the series.
GET /v1/apps/{id}/revenueRevenue and downloads for the app from the connected sources: App Store Connect units, Google Play installs, RevenueCat MRR, subscriptions and trials. connected:false when nothing is connected. Scope revenue:read.
GET /v1/apps/{id}/subscriptionsSubscription event counts from the RevenueCat / Adapty webhook, per day, country and monthly cohort. Scope revenue:read.
GET /v1/apps/{id}/funnelApp Store impressions → product page views → downloads: today's point and the day-by-day history from App Store Connect analytics. Scope revenue:read.
GET /v1/apps/{id}/pricingPrices in force per product and country and every fixed-price period with its trials, paid starts and revenue, plus offer codes, from the RevenueCat / Adapty webhook. Scope revenue:read.
GET /v1/apps/{id}/campaignsApple Ads campaigns promoting the app (matched by App Store id): spend, taps, installs, budget and status, plus the top keywords and search terms. Scope ads:read.

Endpoints below /apps/{id} take country (a storefront code such as us, defaulting to the app's first) and, where both stores are measured, platform=ios|android.

The three measurement states survive the boundary

This is the part worth reading before you write the integration. A rank field can be a number, but the absence of a number is two different things and the API keeps them apart:

  • measured: true, rank: 7 — the app was found at position 7.
  • measured: true, rank: null — the search ran and the app was not in the results down to searchDepth.
  • measured: false — the search could not be run that day. Nothing is known about the position.
JSON
{
  "country": "de",
  "platform": "ios",
  "live": true,
  "measuredAt": "2026-09-19T02:14:08.921Z",
  "keywords": [
    { "term": "traumdeutung", "measured": true,  "rank": 7,    "demand": 6, "searchDepth": 200 },
    { "term": "traumsymbole", "measured": true,  "rank": null, "demand": 3, "searchDepth": 200 },
    { "term": "traumtagebuch", "measured": false, "rank": null, "demand": null, "searchDepth": null }
  ]
}

Folding the last two into a zero would describe a collapse that never happened, and every average built on top of it would be wrong. If your code needs one number, treat measured: false as a gap in the series, not as a value.

Account, usage and search

Four endpoints about the key itself and the account's own records. The first two cost nothing, so a script can check what it may read and how much is left before it starts. search and fetch follow the shape ChatGPT expects from a deep-research connector: a query returns ids, an id returns the record.

EndpointWhat it returns
GET /v1/accountWho the key belongs to: plan, authentication method, scopes, readable apps, credit balance. 0 credits.
GET /v1/usageEvery quota with used / limit / reset, today's Hive allowance and the per-second rate. 0 credits.
GET /v1/search?q=Search your own apps, tracked keywords and rivals; returns ids for /v1/fetch (ChatGPT deep-research shape).
GET /v1/fetch?id=The full record behind a search id: app card, one keyword with history, or one rival with the terms it beats you on.

Hive: any app, any market

The endpoints above read your own tracked apps. Hive endpoints read what the whole network measures — charts, any app's daily measure, keyword result lists, a rival's keywords and any app's revenue and downloads. They need their own scope on the key and cost more credits per call; each plan also has a daily Hive allowance so a month of credits lasts a month.

EndpointWhat it returnsScope
GET /v1/hive/charts?country=&kind=&genre=A storefront's Top Free, Top Grossing or iPad list (100 deep) as of its latest day.hive:read
GET /v1/hive/apps/{storeId}?country=Any app's latest daily measure: ratings, rating, version, price, star distribution, category badge, plus supported languages, upcoming in-app events, promotional text and featured in-app purchases.hive:read
GET /v1/hive/keywords/{term}/ranks?country=&days=&top=Who ranked for a keyword, day by day (1,000 rows per call).hive:read
GET /v1/hive/spy/{storeId}?country=The keywords a rival ranks for — same privacy filter and monthly spy allowance as the dashboard.hive:spy
GET /v1/hive/estimate/{storeId}?country=Monthly revenue and downloads of any App Store app, worldwide (202 while the first read runs).hive:estimate
GET /v1/hive/movers?country=&kind=&genre=&days=&limit=Who climbed, who fell, who entered and who left one top chart, against the same chart N days ago. Every delta is drawn between two measured days, and the answer names both of them.hive:read
GET /v1/hive/new?days=&country=&limit=Apps seen on a top chart for the first time, newest first. The answer carries how many of those days the index covers, so every first-seen date is a day we indexed.hive:read
GET /v1/hive/find?genre=&country=&kind=&released=&rankMin=&rankMax=&text=&publisher=&page=Find apps across the charts we measure: filter by category, storefront, chart (Top Grossing, Top Free, Top Paid, Top iPad), rank band, first-seen date, name or publisher. Every row carries the app's revenue and downloads.hive:read
GET /v1/hive/gap?ids=&country=&platform=Keyword gap for up to five apps side by side: which term each one ranks for and which it misses. Hive Explorer. Same privacy filter as spy, and each app carries its own measurement state so every cell in the table is a measured fact.hive:spy
GET /v1/hive/publisher/{publisherId}Every app of one publisher that Hive has seen, with the day each was first charted.hive:read
GET /v1/hive/resolve?q=&country=&limit=Any app's id from a name, developer, store link, App Store id or package name. Names go through the App Store search in that storefront.hive:read
GET /v1/hive/similar/{storeId}?country=The store's similar-apps shelf for any app, in shelf order, with each app's category and name and the day the shelf was read.hive:read
GET /v1/hive/reviews/{storeId}?country=&limit=Any app's recent reviews in one storefront with the star distribution; reviewer names left out.hive:read

Nothing personal crosses this line: review authors never appear, and a rival's keyword only shows when at least two other accounts track it or you do.

Try it without a key

Every path also exists under /v1/sandbox/ with no key at all: the same shapes, a fixed two-app dataset, dates that move with yesterday. Responses carry x-sandbox: true. For CI you can create a test key (sl_test_) in Settings — it answers only from the sandbox, spends no credits and works on every plan, so a leaked test key exposes nothing.

Terminal
curl -s https://storelift.net/v1/sandbox/apps
curl -s 'https://storelift.net/v1/sandbox/hive/keywords/sleep%20sounds/ranks?country=us&days=3&top=10'

How writes and scopes work

  • Every write is previewed first. Reads are GET. POST /v1/actions returns the before/after diff, the credit cost and a single-use token, changing nothing; POST /v1/actions/confirm applies it. The token is bound to the action, the arguments and the target's state at preview time, so if the target moved in between the confirm returns confirm_token_mismatch with the new diff and writes nothing. The actions cover keywords, rivals, apps, share links and review replies (Pro and above), and on Studio listing text on an editable App Store version and Apple Ads pause, resume and daily budget. The full list is in the reference.
  • Write scopes are opt-in. Each write needs its scope (track:write, reports:write, reviews:write, ads:write, listing:write); they start unchecked when a key is created. Test keys answer from the sandbox and leave your data as it is. Billing stays in your account settings.
  • Read the returned observation date and state. A response can contain a retained measurement, verified absence, pending work or an error. Repeating a request does not make an older observation new.
  • The revenue layer is behind its own scopes. The ten growth endpoints (revenue, subscriptions, funnel, pricing, change-impact, campaigns, ads-keywords, ads-search-terms, ads-commands, search-popularity) answer to a key created with the sensitive revenue:read / ads:read scopes, so a key opens revenue data only when you choose it. GA4 lives in the dashboard.
  • History follows the plan. history and charts both use the plan's window, so the same key reaches exactly as far through either endpoint.

Errors

StatuserrorWhen
400key_in_urlThe key was sent in the URL, where logs and proxies keep it. Send it in the x-api-key header and rotate it; the workspace admins get one email per key.
401missing_api_keyNo key in the request.
401invalid_api_keyThe key is unknown or was revoked.
401account_deletedThe account behind the key is gone.
403plan_requiredThe plan does not include API access. The response carries the current plan.
405method_not_allowedReads are GET; POST is taken on /v1/actions, /v1/actions/confirm and /v1/apps/{id}/validate-listing (the draft travels in the body).
400unknown_actionThe action name is not in the catalog; the response lists the ones that are.
400invalid_argumentsAn argument is missing or malformed; the response names the field.
409confirm_token_expiredThe token is older than 10 minutes. Preview again.
409confirm_token_mismatchThe target changed after the preview; the response carries the new diff.
403write_limit_reachedThe write is outside the guardrails (budget step, daily Apple Ads actions, daily writes: 200 tracking / 50 review replies).
403test_key_read_onlyTest keys never write.
404job_not_foundNo job with that id in this workspace.
403workspace_suspendedThe workspace is suspended; support can say why.
403ip_list_requiredThis workspace requires every key to carry an IP allow list.
404not_foundThat app id is not in this account.
404unknown_endpointNo such path under /v1.
402credits_exhaustedThis month's credits are used up; the response links to the credit pack.
429rate_limitedToo many requests for this key; wait for the Retry-After seconds.
429daily_hive_limitToday's Hive allowance for the plan is used up; resets at 00:00 UTC.
404not_measuredNo verified observation is available for the requested app, keyword or scope. Missing data is not zero. Check the request parameters and follow the linked documentation for available actions.
400bad_query/v1/search needs q of 1–120 characters.
400bad_id/v1/fetch needs an id exactly as /v1/search returned it.
403asc_requiredupdate_listing needs a connected App Store Connect key.
403asc_roleThe App Store Connect key needs the Admin or App Manager role to edit metadata.
409no_editable_versionNo App Store version is editable; the response lists the current version states.
404locale_not_foundThat storefront language is not on the version; the response lists the ones that are.
409changed_since_previewThe listing changed in App Store Connect after the preview; nothing was written.
422asc_rejectedApp Store Connect refused the change; its own message is in detail.
409in_progressA write for the same target is still running.
403ip_not_allowedThe key has an IP allow list and this request came from elsewhere.
401key_leakedThe key was found in a public repository and revoked automatically; create a new one.

Every error is JSON with an error field. plan_required also returns plan, so a client can say which plan the key is on rather than guessing.

Frequently asked

Is there a rate limit?

Yes, per key: requests per second by plan (429 with Retry-After), a monthly credit allowance shown in the x-credits-* headers, and a daily Hive allowance. Each call also updates a usage counter on the key so you can see in Settings whether an old key is still in use.

Can I use it on the free plan?

Live keys for the API start at Pro. The keyless sandbox and test keys work on every plan, the remote MCP server starts on Pro too, the free tools on this site need no account at all, and the free plan measures one app daily.

API or MCP server?

A script wants the API: fixed shapes, one call, no model in the loop. An assistant wants the MCP server, because the tools carry their own descriptions and it can pick the right call without you writing the integration. Both work on the same measurements, and both write through the same preview-then-confirm step.

See this for your own app

Paste your store link, add your keywords. Rank, the apps above you and demand are measured every day.

Free plan: 1 app, 10 keywords in each of 2 storefronts, 14 days of history, no card, no end date. Pro is $29/mo.

Start free →
Competitor sets · the terms you share with one competitor and the ones only it has

Read next