Developer docs › API reference
Your apps endpoints
The apps this workspace tracks: ranks, rivals, reviews, store page, listing timeline, featuring, charts and listing checks.
Authentication · Credits · Common parameters · Error codes · openapi.json
GET /apps
List the apps tracked in this Storelift account (id, name, countries, keywords). Call this first — every other tool needs an appId from here.
curl "https://storelift.net/v1/apps" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/keywords
Keyword ranks for one app in one App Store / Google Play country. THREE STATES ARE DISTINCT: measured=false means the query could not be measured, rank=null means it was measured but the app is absent from the top results, rank=<number> is the rank. Never collapse them into one — counting an unmeasured day as zero produces a false answer.
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/keywords?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/rivals
Apps that rank ABOVE this app in search. For each rival you get the keywords it beats you on, its rank there (theirRank) and yours (ourRank) — ourRank null means the app does not appear for that keyword at all.
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/rivals?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/ai
App mentions in a dated sample of AI engine answers; this does not reproduce what ChatGPT, Claude or Gemini show each user. Studio or Enterprise and the ai:read scope are required. engines holds each measured engine's answers; providers gives measured, failed or not_measured states. An unavailable engine is not a zero score. Read the dated sample and its question count; it is not a universal ranking or a measure of all consumer answers.
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/ai?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/ai-check
Start an AI visibility sample for one app in one country, with the engines available for the run. Requires Studio or Enterprise and the ai:read scope; Pro's panel allowance does not grant access to this MCP tool. Uses one plan or purchased AI visibility run; get_ai_visibility returns the result. One measurement per app runs at a time.
| Parameter | In | Type | Description |
|---|---|---|---|
country | query | string | country code, e.g. tr, us (empty = the app's first three countries) |
Also takes: appId (required)
Besides its credits, this call uses one plan or purchased AI visibility run, so there is no command to copy here.
GET /apps/{appId}/history
Keyword rank history for one country. Series points are [day, rank]; a null rank means the app was absent from the top results that day, which is not the same as a bad rank. Pro plan.
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/history?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/page
The app's own store listing signals for one country (name and subtitle are not included): version, in-app events, editorial placements, similar-apps shelves and the screenshot set (iOS), plus the Google Play page (exact install count, rating histogram, ad/IAP flags, chart badge). ios.listingExtras holds the languages the app supports, its star breakdown (1★ to 5★), live and upcoming in-app events, the promotional text and the featured in-app purchases; on Free it carries the language count, the first 5 languages and the star breakdown, and locked shows how many of the rest there are. timeline lists the dated changes we detected on the listing — the cheapest explanation for a rank move. measured=false means the page was never read; it is not the same as an empty page.
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/page?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/reviews
Recent reviews for one country: list holds the App Store reviews, android the Google Play reviews (a shorter window), each with its text, rating and date. newCount is how many arrived since the previous measurement; on an older record it arrives as null, so read it as unknown rather than zero. android: null means that Play page is awaiting its first measurement, and an empty list means the page has no reviews.
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/reviews?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/charts
App Store chart position for one country: current ranks per list (free / paid / grossing, overall and in category) plus their history. Google Play is absent on purpose — it has no public top chart, and a number here would be invented.
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/charts?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/reviews/search
Search one app's reviews in one storefront by text, star rating, app version and date range, newest first — up to 1,000 rows from the full review archive within your plan's review window. total is the match count; truncated tells you when more rows matched than you asked for.
| Parameter | In | Type | Description |
|---|---|---|---|
q | query | string | text to find in the review title or body |
rating | query | string | star ratings, comma separated, e.g. 1,2 |
version | query | string | app version the review was written on, e.g. 2.4.0 |
from | query | string | first day, YYYY-MM-DD |
to | query | string | last day, YYYY-MM-DD |
limit | query | number | rows, up to 1000 (default 100) |
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/reviews/search?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/reviews/stats
Star-rating distribution, average and share of 1–2 star reviews for one app in one storefront, plus a day-by-day curve (count and average per day) and a per-version breakdown — so a drop lines up with the release that caused it. Defaults to the last 90 days.
| Parameter | In | Type | Description |
|---|---|---|---|
days | query | number | last N days, up to 365 (default 90) |
from | query | string | first day, YYYY-MM-DD (overrides days) |
to | query | string | last day, YYYY-MM-DD |
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/reviews/stats?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/reviews/summary
Review AI for one app in one storefront: a summary of the recent reviews and the themes in them — complaints, requests, praise — each with the reviews quoted as evidence. The same day and the same review batch return the stored summary at no allowance; a new summary uses one Review AI credit from the monthly allowance (every plan; Free has a taste). Answers state: "too_few" with the count while there are too few reviews to summarise.
| Parameter | In | Type | Description |
|---|---|---|---|
store | query | ios | android | defaults to ios |
lang | query | en | tr | de | es | fr | pt | ru | ja | ko | zh | language of the summary (default en) |
Also takes: appId (required) · country
Besides its credits, this call uses one Review AI credit from the monthly allowance, so there is no command to copy here.
GET /apps/{appId}/reviews/reply-draft
A developer reply draft for one review, in the storefront's language. The review's rating and text come from the stored review on our side, so the draft answers what the reviewer actually wrote; note adds what you want the reply to say (a fix shipped, a setting to try). The draft is returned only — reply_review posts a reply after your confirmation. Uses one Review AI credit.
| Parameter | In | Type | Description |
|---|---|---|---|
store | query | ios | android | defaults to ios |
reviewIdrequired | query | string | review id from get_reviews or search_reviews |
note | query | string | what the reply should say, e.g. fixed in 2.4.1 |
Also takes: appId (required) · country
Besides its credits, this call uses one Review AI credit, so there is no command to copy here.
GET /apps/{appId}/timeline
Dated changes to one app's listing — new version, screenshots, in-app events, featuring from the store page, and keyword-field edits from App Store Connect — each with the keyword rank movement around it: terms that went up, down, entered or dropped between the last measurement before the change and the last one within window days after, plus the five biggest moves.
| Parameter | In | Type | Description |
|---|---|---|---|
window | query | number | days after each change to read ranks, up to 30 (default 7) |
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/timeline?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/today
One app's day in one answer — the Today screen: purchases, trials and renewals from the connected sources, new reviews, rank and category moves against yesterday, new entrants above you, new in-app events, and yesterday's App Store, Google Play, proceeds and ads figures, each marked with the source it came from. tz makes "today" the user's own day.
| Parameter | In | Type | Description |
|---|---|---|---|
tz | query | string | IANA time zone, e.g. Europe/Istanbul (defaults to UTC) |
day | query | string | another day to read, YYYY-MM-DD |
Also takes: appId (required)
curl "https://storelift.net/v1/apps/sbx-lumen/today" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/competition
How many apps compete on each keyword in one storefront, returned for terms seen on two or more apps. Defaults to the app's tracked keywords; pass terms to count candidates before you track them. corpus is the size of the set behind the count.
| Parameter | In | Type | Description |
|---|---|---|---|
terms | query | string | up to 100 terms, comma separated (defaults to the tracked keywords) |
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/competition?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/rivals/{rivalId}
One rival of your app in one storefront: its name, rating and rating count with a 90-day history of them (a name change is how a listing rewrite shows), and the keywords it ranks for with its rank on each. The keyword list uses one keyword spy from the monthly allowance and stays open for 30 days; when the allowance is used up the answer carries the rival's own figures with locked: true.
| Parameter | In | Type | Description |
|---|---|---|---|
rivalIdrequired | path | string | rival id from get_rivals |
Also takes: appId (required) · country · platform
Besides its credits, this call uses one keyword spy from the monthly allowance, so there is no command to copy here.
GET /apps/{appId}/rivals/{rivalId}/adnetworks
How a rival monetises with ads: the ad networks it works with, each marked DIRECT or RESELLER. The state keeps the cases apart — the networks found, a developer that declares no ad networks (no_file), a check that could not complete this time (unreachable) or a listing with no developer website (no_site). Kept for 14 days.
| Parameter | In | Type | Description |
|---|---|---|---|
rivalIdrequired | path | string | rival id from get_rivals |
Also takes: appId (required) · platform
curl "https://storelift.net/v1/apps/sbx-lumen/rivals/1000000001/adnetworks" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/rivals/{rivalId}/market
A rival's market in one storefront: on Google Play the exact install count and in-app purchase price range, and the installs between two measurements once there are two; on the App Store its price, rating count, release date and whether it sells in-app purchases. Measured on request and kept for 7 days.
| Parameter | In | Type | Description |
|---|---|---|---|
rivalIdrequired | path | string | rival id from get_rivals |
Also takes: appId (required) · country · platform
curl "https://storelift.net/v1/apps/sbx-lumen/rivals/1000000001/market?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/storefront-audit
Your iOS listing in every App Store storefront: where the app is sold, which storefronts serve the fallback text or the fallback screenshots instead of their own language, and the second locale each storefront also indexes. Returns the last scan; refresh: true starts a new one when the last is older than 12 hours and answers 202 with eta seconds — call again after that. The full table is on Pro and above; Free gets the preview.
Also takes: appId (required)
curl "https://storelift.net/v1/apps/sbx-lumen/storefront-audit" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/suggest
New keyword ideas for one app in one storefront, written in that storefront's search language: terms of 1–3 words people type into the store search box, each with a one-line reason naming who searches it and why the app answers that need. Tracked keywords, keywords you buried and brand names stay out. Uses one AI writing credit from the monthly allowance (Pro and above); measure the ideas with get_keyword_metrics before you track them.
| Parameter | In | Type | Description |
|---|---|---|---|
cc | query | string | storefront code, e.g. tr, us (defaults to the app's first country) |
lang | query | en | tr | de | es | fr | pt | ru | ja | ko | zh | language of the reasons (default en) |
Also takes: appId (required)
Besides its credits, this call uses one AI writing credit from the monthly allowance, so there is no command to copy here.
POST /apps/{appId}/validate-listing
Check a draft App Store listing before it goes to App Store Connect. It reports character limits per field, keyword-field room lost to spaces, repeats, words already in the name or subtitle, the brand and filler words, name/subtitle repeats, Apple product names and price words, whether the text is in the locale's language and script, and which of the app's tracked keywords the draft leaves out. Writes nothing; pass only the fields you want checked.
| Parameter | In | Type | Description |
|---|---|---|---|
locale | body | string | listing locale, e.g. en-US, de-DE, ja |
country | body | string | country whose tracked keywords to check coverage against, e.g. us (defaults to the app's first country) |
name | body | string | app name, up to 30 characters |
subtitle | body | string | subtitle, up to 30 characters |
keywords | body | string | keyword field, comma-separated, up to 100 characters |
promotionalText | body | string | promotional text, up to 170 characters |
description | body | string | description, up to 4000 characters |
Also takes: appId (required)
curl -X POST "https://storelift.net/v1/apps/sbx-lumen/validate-listing" \
-H "Authorization: Bearer $STORELIFT_API_KEY" \
-H "content-type: application/json" \
-d '{"locale":"en-US","name":"Lumen: Sleep Sounds","subtitle":"White noise and rain for sleep","keywords":"calm,relax,nap,baby,fan,ocean,lullaby"}'GET /apps/{appId}/draft
A listing draft — title, subtitle, promotional text and description — built from the keywords measured for this app in one storefront, ordered by demand. Every field comes with its character count against the store limit, plus two review checks: an Apple product name in the title or subtitle (App Store only) and pricing language. termsUsed lists the measured terms behind it; excluded the tracked terms still to be measured. Nothing is written to the store — update_listing does that. Uses one AI writing credit (Pro and above).
| Parameter | In | Type | Description |
|---|---|---|---|
cc | query | string | storefront code, e.g. tr, us (defaults to the app's first country) |
Also takes: appId (required) · platform
Besides its credits, this call uses one AI writing credit, so there is no command to copy here.
GET /apps/{appId}/localize
Write the full App Store listing for a new locale — name, subtitle, keyword field and description — from the app's source listing, with every keyword measured in that storefront first. The first call starts the write and answers pending (it takes one listing write from the plan: Free 1 in total, Pro 20 and Studio 75 a month); call again with poll=true until the listing comes back. With shots=true the screenshot captions come back in the same language too. Needs get_storefront_audit to have run for the app. Writes nothing to App Store Connect; update_listing does that.
| Parameter | In | Type | Description |
|---|---|---|---|
localerequired | query | string | target locale, e.g. de_de, pt_br, ja_jp (de-DE also works) |
Also takes: appId (required)
Besides its credits, this call takes one listing write from the plan, so there is no command to copy here.
GET /apps/{appId}/shot-text
The caption text on your first four App Store screenshots in one storefront. Apple indexes the listing text, so this text works on conversion rather than search rank — the answer says so with indexed: false. Kept until the screenshots change; a new read uses one AI writing credit (Pro and above).
| Parameter | In | Type | Description |
|---|---|---|---|
cc | query | string | storefront code, e.g. tr, us (defaults to the app's first country) |
Also takes: appId (required)
Besides its credits, this call uses one AI writing credit, so there is no command to copy here.
GET /apps/{appId}/chart-movers
Who moved in the app's own category chart: risers and fallers (3+ places), new entrants and drop-outs, with names, plus where the app itself and its chosen rivals stood on both days. The category comes from the app's chart record; pass genre to look at another. Pro plan.
| Parameter | In | Type | Description |
|---|---|---|---|
kind | query | free | paid | grossing | chart (default free) |
genre | query | string | App Store genre id, e.g. 6013 (defaults to the app's own category) |
days | query | number | compare with this many days ago, 1-90 (default 1) |
limit | query | number | rows per bucket, up to 100 (default 25) |
Also takes: appId (required) · country
curl "https://storelift.net/v1/apps/sbx-lumen/chart-movers?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}/featuring
Where Apple shows the app today, per country: editorial cards (dedicated: true when the story is about this app, false when it sits in a collection), live and scheduled In-App Events, Apple's You Might Also Like shelf, and the dated history of featurings and new events. Leave country empty for every country the app tracks.
| Parameter | In | Type | Description |
|---|---|---|---|
country | query | string | country code, e.g. tr, us (empty = every country the app tracks) |
Also takes: appId (required)
curl "https://storelift.net/v1/apps/sbx-lumen/featuring?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"GET /apps/{appId}
One tracked app with its platform ids, countries, tracked keywords per country and the latest measurement snapshot (per-country keyword tables). Use list_apps first to get the appId.
Also takes: appId (required)
curl "https://storelift.net/v1/apps/sbx-lumen" \
-H "Authorization: Bearer $STORELIFT_API_KEY"Sample response
GET /apps/{appId}/weekly-plan
This week's listing suggestions for the app — the same list as the dashboard's "This week" card, best first. A suggestion only appears when it passes strict checks: a keyword goes into the title or subtitle only if it is a core, high-demand term of the app's niche, the app already ranks #4–15 for it, rival apps above carry it in their name and it fits without dropping the brand or anything that ranks; niche or long-tail keywords go to the keyword field at most, only when there is room; other categories, other languages and keywords the user turned down never appear; nothing is suggested while a recent listing change is still settling (settling says until when). Each task has the sentence, the current and proposed text, the words it adds and removes, the reasons (measured facts), the trade-off and a confidence. Without country, all storefronts are merged and the same change is one task with its countries. Often empty — that is on purpose. Pro plan.
| Parameter | In | Type | Description |
|---|---|---|---|
country | query | string | one storefront, e.g. tr, us (omit to merge all storefronts) |
goal | query | downloads | rank | revenue | accepted for compatibility; suggestions are ordered by expected value |
platform | query | ios | android | store (default ios) |
limit | query | integer | tasks to return, 1–10 (default 5) |
Also takes: appId (required)
curl "https://storelift.net/v1/apps/sbx-lumen/weekly-plan?country=us" \
-H "Authorization: Bearer $STORELIFT_API_KEY"