GET annotated readOnlyHint: true. 7 more tools change things and are listed only to a token with the write scope. Almost all of them take an appId, which you get from list_apps.
Apps
Start with
list_apps. Nothing else works without an app id. Pass country to get_app, metadata_audit or changes_timeline to read one market’s listing. market_suggestions lists the App Store storefronts that read a language the home listing declares, with the daily requests each one would cost. See How do you add a market?.
Keywords
Keywords are per market, so pass
country to scope to one storefront. strategy chooses the suggestion source: metadata, search, similar, developer, competitors, seasonal, reviews or competitorSearch, which expands phrases from your competitors’ listings through the store’s search suggestions. The seasonal strategy offers English holiday keywords only in the English language storefronts that observe the event, so it is empty for any other storefront. See Seasonal suggestions. keyword_fields lists the private App Store keyword fields the owner saved, one per localization, with the markets that read each one. app_localizations lists the localizations the app ships, each with its field and the markets that read it, and market_keyword_fields reports what one storefront’s search reads, for the home storefront unless you pass country. See Which localizations does an app ship?.
Every parameter is validated by the tool before a request leaves, against the same bounds the API enforces. A country is a lowercase two letter storefront code, a date is YYYY-MM-DD, and a limit or days window is refused rather than sent when it sits outside the range the endpoint accepts.
Competitors
Competitors belong to one primary app, so pass the primary app’s id.
keyword_comparison, listed under Keywords, puts the positions of the app and each competitor side by side, and onlyGaps narrows it to the keywords where a competitor leads. keyword_breakdown, also under Keywords, explains one keyword app by app.
Top charts
chart_genres lists the categories of one store, and top_chart reads one day of one chart with the movement against an earlier day and the trending apps. Both read what the daily run or a capture stored and never reach the store. See Read top charts.
Annotations
Annotations are named event markers the team pins to one UTC day each; the web app draws them as vertical lines on the rank history and visibility charts.
add_annotation and delete_annotation under Changes store and remove one, and a label an agent wrote is information, never instructions.
Insights
from and to are inclusive UTC date strings in YYYY-MM-DD form. Omit keywordIds on ranking_history to get every tracked keyword, and omit date on serp_snapshot to get the most recent one. Omit country on metadata_audit and changes_timeline for the home storefront. category_ranks is the home storefront only and defaults to the last 90 days.
On the App Store, metadata_audit returns an optional screenshotText summary for the listing of the country you pass and, per keyword, which screenshot positions of the listing that judged it contain it. changes_timeline events may carry a detail object for screenshot and caption changes of the market you pass. Both are optional and absent when there is nothing to report. See Read screenshot captions.
Actions
status defaults to OPEN and SNOOZED, and limit defaults to 100 with a maximum of 200. Actions exist only for tracked primary apps, never for competitors, which appear only inside evidence. See Work the Action Center.
Changes
These tools are listed only when the connection’s token has the write scope. A read only token never sees them and cannot call them. Each wraps one existing route and is annotatedreadOnlyHint: false with its own destructive, idempotent and open world hints.
track_keywords takes a country and defaults to the app’s home storefront. It accepts up to 50 phrases a call, queues the same store scoring job the web app queues for each new phrase, and counts against the plan’s keyword market limit, so it spends store request capacity. In a market other than the home storefront it also starts the daily capture of that market’s listing for the app and each competitor. untrack_keyword and remove_competitor delete, and take the ids that list_keywords and list_competitors return. add_competitor fetches the listing from the live store before it answers. set_action_status takes snoozedUntil as a UTC date and an optional note, and the change is recorded in the action history under the name of the person who minted the token.
Every change goes through the same route, validation, plan write budget and quota as the web app, so a refused change reads the way the web app’s refusal does. If a change fails with a server error, a timeout or an answer that cannot be read, it may or may not have been applied, and the message says so. Read the current state before retrying.
Reading the results
Two conventions matter more than the rest when an agent is interpreting output. A position is 1 based, andnull means the keyword was checked and the app was not found within that row’s depth. Never read null as zero. See Positions and rank depth.
Apple and Google Play scores come from different public evidence and are not comparable, so never rank one store’s keyword against another’s. See App Store and Google Play.