# Your apps endpoints

> https://storelift.net/docs/api/apps/

The apps this workspace tracks: ranks, rivals, reviews, store page, listing timeline, featuring, charts and listing checks. Base URL `https://storelift.net/v1` · authentication, credits and common parameters: https://storelift.net/docs/api/

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Free

```sh
curl "https://storelift.net/v1/apps" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/keywords?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/rivals?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `ai:read` · Credits: 1 · Plan: Studio

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/ai?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `ai:read` · Credits: 1 · Plan: Studio

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (empty = the app's first three countries)

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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/history?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/page?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `reviews:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/reviews?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/charts?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `reviews:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios
- `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)

```sh
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.

Scope: `reviews:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios
- `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

```sh
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.

Scope: `reviews:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `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)

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.

Scope: `reviews:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `store` (query, ios | android) — defaults to ios
- `reviewId` (query, string, required) — review id from get_reviews or search_reviews
- `note` (query, string) — what the reply should say, e.g. fixed in 2.4.1

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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios
- `window` (query, number) — days after each change to read ranks, up to 30 (default 7)

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `tz` (query, string) — IANA time zone, e.g. Europe/Istanbul (defaults to UTC)
- `day` (query, string) — another day to read, YYYY-MM-DD

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios
- `terms` (query, string) — up to 100 terms, comma separated (defaults to the tracked keywords)

```sh
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`.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `rivalId` (path, string, required) — rival id from get_rivals
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios

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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `rivalId` (path, string, required) — rival id from get_rivals
- `platform` (query, ios | android) — defaults to ios

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `rivalId` (path, string, required) — rival id from get_rivals
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Pro

- `appId` (path, string, required) — app id from list_apps
- `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)

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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `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

```sh
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).

Scope: `apps:read` · Credits: 1 · Plan: Pro

- `appId` (path, string, required) — app id from list_apps
- `cc` (query, string) — storefront code, e.g. tr, us (defaults to the app's first country)
- `platform` (query, ios | android) — defaults to ios

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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `locale` (query, string, required) — target locale, e.g. de_de, pt_br, ja_jp (de-DE also works)

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).

Scope: `apps:read` · Credits: 1 · Plan: Pro

- `appId` (path, string, required) — app id from list_apps
- `cc` (query, string) — storefront code, e.g. tr, us (defaults to the app's first country)

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.

Scope: `apps:read` · Credits: 1 · Plan: Pro

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (defaults to the app's first country)
- `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)

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps
- `country` (query, string) — country code, e.g. tr, us (empty = every country the app tracks)

```sh
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.

Scope: `apps:read` · Credits: 1 · Plan: Free

- `appId` (path, string, required) — app id from list_apps

```sh
curl "https://storelift.net/v1/apps/sbx-lumen" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```

## 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.

Scope: `apps:read` · Credits: 1 · Plan: Pro

- `appId` (path, string, required) — app id from list_apps
- `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)

```sh
curl "https://storelift.net/v1/apps/sbx-lumen/weekly-plan?country=us" \
  -H "Authorization: Bearer $STORELIFT_API_KEY"
```