API reference

The threefold HTTP API is described by an OpenAPI 3.1.0 document generated from the endpoint registry. The live copy is at https://api.threefold.eco/openapi.json; this page is rendered from the copy committed with the typed clients (clients/openapi.json, API version 0.2.0).

Base URL: https://api.threefold.eco. Authentication: Authorization: Bearer <key> (tf_live_…, or sandbox tf_test_…), an OAuth 2.1 access token, or nothing for keyless library reads. See REST API for headers, paging and metering, and Errors for error bodies.

Account

Library Metadata

GET /api/meta library_meta

Library overview - configured markets, niches, the first-cut profile and data counts

Track App

POST /api/track track_app

Track an app across markets - ingest it now and keep it on your workspace with a home and target markets

Name	In	Required	Type	Description
`id`	body	yes	string
`home`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`targets`	body		(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]	Defaults to the first library cut minus home
`pillars`	body		string[]	brand, organic, paid

Account Usage

GET /api/usage usage

Your workspace's plan, tracked apps and spend this month

Request Coverage

POST /api/coverage/request request_coverage

Record a market, app or channel you need that is not yet covered by Threefold

Name	In	Type	Description
`market`	body	string	Market code or country name needed, e.g. br, pl, kr
`app_id`	body	string	App id or package name needed
`channel`	body	string	Channel or source needed, e.g. line, kakao, reddit
`note`	body	string	Context on why this coverage is needed

Save Item

POST /api/collections/save save_item

Save research items (apps, screens, galleries, comparisons) to a collection or workspace

Name	In	Required	Type	Description
`item_id`	body	yes	string	Item identifier to save
`kind`	body		app \| screen \| gallery \| comparison	Kind of saved item
`collection_id`	body		string	Collection UUID or 'all-saved'
`collection_name`	body		string	Name of collection to create or add into
`market_code`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Market code if applicable
`title`	body		string	Item title
`note`	body		string	Optional research note

List Collections

GET /api/collections list_collections

List saved research collections for the current workspace with item counts

Name	In	Required	Type	Description
`limit`	query		integer	Max collections to return
`offset`	query		integer	Paging offset

Get Collection

GET /api/collections/{id} get_collection

Retrieve items and notes in a saved research collection

Name	In	Required	Type	Description
`id`	path	yes	string	Collection UUID or 'all-saved'
`limit`	query		integer	Max items to return
`offset`	query		integer	Paging offset

Add Collection Note

POST /api/collections/notes add_collection_note

Attach a team note or research comment to a collection or saved item

Name	In	Required	Type	Description
`note`	body	yes	string	Note content
`collection_id`	body		string	Collection UUID
`item_id`	body		string	Item identifier

Create Watch

POST /api/watches create_watch

Create an alert watch on an app or niche in markets

Name	In	Required	Type
`target_type`	body	yes	app \| niche
`target_id`	body	yes	string
`markets`	body		(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]
`events`	body		string[]
`threshold`	body		integer
`webhook_url`	body		string
`webhook_secret`	body		string
`email`	body		string

List Watches

GET /api/watches list_watches

List active alert watches for the current workspace

Name	In	Required	Type	Description
`target_id`	query		string

Delete Watch

POST /api/watches/{id}/delete delete_watch

Delete or deactivate an alert watch

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id

Watch Events

GET /api/watches/{id}/events watch_events

Get recent detected events and delivery logs for a watch

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`limit`	query		integer

Workspace

POST /api/agent/workspace agent_workspace

The workspace's apps, competitors per market, target markets, watches and changes, saved items and usage

Name	In	Type	Description
`action`	body	get \| set_apps \| set_competitors \| set_markets \| watch \| unwatch \| changes \| save \| saved	get (default)
`apps`	body	string[]	Names, ids or store URLs
`market`	body	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	set_competitors: the market
`markets`	body	(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]	set_markets, watch
`home`	body	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	set_markets: home market
`item`	body	string	save: JSON object with title, tool, args, note
`since`	body	string	changes: since this date

Analysis

Explain Listing Differences

POST /api/analysis/listing explain_listing

AI explanation of why an app's listing differs between two markets

Name	In	Required	Type	Description
`app`	body	yes	string
`to`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`from`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`refresh`	body		boolean	Ignore the cached result
`task_intent`	body		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	body		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Explain Paid

POST /api/analysis/paid explain_paid

AI explanation of the ad strategy in a market for an app or niche

Name	In	Required	Type	Description
`market`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`app`	body		string
`niche`	body		games \| education \| health-fitness \| finance \| productivity \| lifestyle
`from`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`refresh`	body		boolean
`task_intent`	body		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	body		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Brand Name Check

POST /api/analysis/brand-name brand_name_check

AI check of an app name and tagline for meaning or connotation problems in other markets

Name	In	Required	Type	Description
`name`	body	yes	string
`tagline`	body		string
`markets`	body		(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]
`refresh`	body		boolean
`task_intent`	body		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	body		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Translate

POST /api/analysis/translate translate

Translate short texts such as ad copy or reviews into one target language

Name	In	Required	Type	Description
`texts`	body	yes	string[]
`target`	body		string	Target language code
`variant`	body		string	Regional language variant
`formality`	body		formal \| informal	Formality register (e.g. for German)
`niche`	body		games \| education \| health-fitness \| finance \| productivity \| lifestyle	App Store niche
`market`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Target market code

Describe Video

POST /api/analysis/video describe_video

AI description of a video ad or post - hook, format, on-screen text, cultural cues

Name	In	Required	Type	Description
`url`	body	yes	string	Public http(s) video URL
`thumbnail`	body		string	Public http(s) thumbnail URL
`market`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`refresh`	body		boolean

Visual Brief

POST /api/analysis/visual-brief visual_brief

Vision analysis evaluating screenshot compositions, cultural adaptations, and visual framing

Name	In	Required	Type	Description
`market`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Target market
`niche`	body		games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	App Store niche
`app`	body		string	App id
`query`	body		string	Research query
`position`	body		integer	Screenshot position (1-based, default 1)
`refresh`	body		boolean	Ignore cached analysis
`task_intent`	body		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	body		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

i18n Readiness Rules Catalogue

GET /api/i18n/rules i18n_check_rules

Catalogue of automated internationalization and localization readiness rules across platforms and markets

Name	In	Required	Type	Description
`platform`	query		string	Filter by platform: core, ios, android, web, flutter, react-native, store, legal
`market`	query		string	Filter by market code (e.g. de-DE, es-MX, ja-JP)

Store and Retrieve i18n Reports

GET /api/i18n/reports/{param} i18n_report_api_i18n_reports_param

Store an uploaded i18n readiness report or retrieve a previously stored report by ID

Name	In	Required	Type	Description
`param`	path	yes	string	Report UUID for retrieval

Store and Retrieve i18n Reports

POST /api/i18n/reports i18n_report_api_i18n_reports

Store an uploaded i18n readiness report or retrieve a previously stored report by ID

Name	In	Required	Type	Description
`param`	body		string	Report UUID for retrieval

Market Glossary

GET /api/market-glossary market_glossary_api_market_glossary

Extract domain terms and CTAs used by top-ranked storefront listings in a niche

Name	In	Required	Type	Description
`niche`	query	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`variant`	query		string	Optional regional variant
`store`	query		ios \| play	ios (default) or play
`format`	query		json \| csv \| tsv \| tbx	Export format
`include_foreign`	query		boolean	Keep terms naming another market (flagged foreign_market_reference) in terms and CTAs; default false

Market Glossary

POST /api/market-glossary market_glossary_api_market_glossary

Extract domain terms and CTAs used by top-ranked storefront listings in a niche

Name	In	Required	Type	Description
`niche`	body	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`market`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`variant`	body		string	Optional regional variant
`store`	body		ios \| play	ios (default) or play
`format`	body		json \| csv \| tsv \| tbx	Export format
`include_foreign`	body		boolean	Keep terms naming another market (flagged foreign_market_reference) in terms and CTAs; default false

Variant Lint

POST /api/variant-lint variant_lint_api_variant_lint

Lint arbitrary copy against regional language dialect rules

Name	In	Required	Type	Description
`text`	body	yes	string
`variant`	body	yes	string

Variant Lint

GET /api/variant-lint variant_lint_api_variant_lint

Lint arbitrary copy against regional language dialect rules

Name	In	Required	Type	Description
`text`	query	yes	string
`variant`	query	yes	string

Listing Check

POST /api/listing-check listing_check

Validate proposed localized store copy against store limits and competitive benchmark

Name	In	Required	Type	Description
`niche`	body	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`market`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`title`	body		string
`store`	body		ios \| play	ios (default) or play

Price Points

GET /api/price-points price_points

Analyze what top apps in a niche charge per storefront from stored listing prices

Name	In	Required	Type	Description
`niche`	query	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`store`	query		ios \| play	ios (default) or play

Market Launch Checklist

GET /api/market-launch-checklist market_launch_checklist

Consolidated per-market launch checklist merging B2B, profile, and statutory legal checks

Name	In	Required	Type	Description
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`report_id`	query		string	Optional stored i18n report UUID

Label Profile

GET /api/labels/profile label_profile

Label shares for one market - how its listings, screenshots, ads or posts are labelled (subscription mentions, screenshot type, hook, post format), with item ids

Name	In	Required	Type	Description
`item_type`	query	yes	listing \| screenshot \| ad \| post	What was labelled
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`niche`	query		games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.
`store`	query		ios \| play	Listings and screenshots: ios (default) or play
`chart`	query		free \| paid \| grossing	Listings and screenshots with a niche: chart type (default free)
`top`	query		integer	Listings and screenshots with a niche: the top N of the chart (1-100, default 100)

Language Fit

GET /api/labels/language-fit language_fit

Share of a market's listings, screenshots and ads written in its own language and variant (es-MX in Mexico, not es-ES), with item ids

Name	In	Required	Type	Description
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`niche`	query		games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Listings and screenshots: niche or genre (the top of its chart). Ads: niche only. Omit for the whole market.
`store`	query		ios \| play	Listings and screenshots: ios (default) or play
`chart`	query		free \| paid \| grossing	Listings and screenshots with a niche: chart type (default free)
`top`	query		integer	Listings and screenshots with a niche: the top N of the chart (1-100, default 100)
`item_types`	query		string[]	listing, screenshot, ad (default all three)

App

Get App

GET /api/apps/{id} get_app

One app across storefronts - localised title, copy language, screenshots, ratings and signals per market

Name	In	Required	Type	Description
`id`	path	yes	string	App Store id, or play:<package> for Play-only apps
`markets`	query		(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]	Comma-separated market codes. Defaults to every market.
`store`	query		ios \| play	ios (default) or play
`include_images`	query		boolean	Fetch and return low-res preview images (default false)
`image_format`	query		webp \| jpg	Preview image format (webp default, or jpg)

Screenshot Gallery

GET /api/visuals/gallery screenshot_gallery

Side-by-side screenshot gallery across markets for one app or top apps in a niche with inline low-res previews and high-res export links

Name	In	Type	Description
`app`	query	string	App Store id (or play:<package> for Play-only apps)
`markets`	query	(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]	Comma-separated target market codes
`market`	query	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Market for niche mode
`niche`	query	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche for top apps mode
`store`	query	ios \| play	ios (default) or play
`limit`	query	integer	Maximum screenshots or apps (1-20, default 5)
`image_format`	query	webp \| jpg	Preview image format (webp default, or jpg)
`task_intent`	query	string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	query	code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

App

GET /api/agent/app agent_app

One app across stores, Brand, Paid and Organic, and markets, as a digest with links and next steps

Name	In	Required	Type	Description
`app`	query	yes	string	App name, App Store id, play:<package> or store URL
`markets`	query		(gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl)[]	Markets to cover (default: where the app charts, up to 5)
`store`	query		ios \| play	ios or play (default: both where linked)
`focus`	query		overview \| brand \| paid \| organic \| reviews \| changes	overview (default) or one part in depth
`platform`	query		string	Paid/Organic platform filter
`format`	query		string	Creative format filter
`since`	query		string	Only items observed on or after this date
`cursor`	query		string	Cursor from a previous answer

Brief

Market Brief

GET /api/apps/{id}/brief market_brief

Rules-based market-entry brief for moving one app into one market across Brand, Paid and Organic

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`to`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Target market
`from`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Home market
`store`	query		ios \| play	ios (default) or play
`task_intent`	query		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	query		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

B2B Market Checklist

GET /api/b2b b2b_checklist_api_b2b

B2B market-entry checklist - procurement, compliance and channels for selling software into a market

Name	In	Required	Type	Description
`market`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Omit for the index of covered markets

B2B Market Checklist

GET /api/b2b/{market} b2b_checklist_api_b2b_market

B2B market-entry checklist - procurement, compliance and channels for selling software into a market

Name	In	Required	Type	Description
`market`	path	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Omit for the index of covered markets

Market Entry Report

GET /api/reports/market-entry market_entry_report

Printable market-entry report for one app moving into one market (HTML, PDF or JSON)

Name	In	Required	Type	Description
`app`	query	yes	string
`to`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`from`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`format`	query		html \| pdf \| json	html (default)
`task_intent`	query		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	query		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Market Entry Narrative

POST /api/analysis/brief market_entry_narrative

AI-written market-entry brief citing listings, ads and posts as evidence

Name	In	Required	Type	Description
`app`	body	yes	string
`to`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`from`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`refresh`	body		boolean
`task_intent`	body		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	body		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Market Take

GET /api/market-take market_take

The weekly threefold take on one market and niche - a headline and evidenced points on how its listings, screenshots, ads and posts differ from the US

Name	In	Required	Type	Description
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Any market except the reference (us)
`niche`	query	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle
`week`	query		string	ISO week YYYY-WW (default: the latest take)

Check

POST /api/agent/check agent_check

Grade the user's listing, screenshots, ad, name, repository or live app for a target market - rule checks, criteria and reference examples

Name	In	Required	Type	Description
`market`	body	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`what`	body	yes	listing \| screenshots \| ad \| name \| repo \| website \| app
`url`	body		string	For what: website: the page to check (home or pricing page)
`genre`	body		string	Genre in plain words or a slug
`from`	body		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	The user's home market
`app`	body		string	App name, id or store URL
`name`	body		string	For what: name
`listing`	body		string	For what: listing. JSON object: title, subtitle, keywords, promotional_text, description, screenshot_count
`store`	body		ios \| play	ios or play

Chart

Top Apps

GET /api/chart top_apps

Top free, paid or grossing apps in one market and niche or genre, with localisation signals and the market profile

Name	In	Required	Type	Description
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`niche`	query	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`store`	query		ios \| play	ios (default) or play
`chart`	query		free \| paid \| grossing	Chart type: top free (default), top paid or top grossing

Compare

Compare Markets

GET /api/compare compare_markets

Compare one niche in two markets - shared winners, apps that have not crossed over, local-only winners

Name	In	Required	Type	Description
`from`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Home market
`to`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Target market
`niche`	query	yes	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`store`	query		ios \| play	ios (default) or play
`chart`	query		free \| paid \| grossing	Chart type: top free (default), top paid or top grossing
`include_images`	query		boolean	Fetch and return low-res preview images (default false)
`image_format`	query		webp \| jpg	Preview image format (webp default, or jpg)
`task_intent`	query		string	Caller task intent or context, used to shape output and logged (hashed)
`output_destination`	query		code \| doc \| chat \| design_tool	Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)

Compare Paid

GET /api/apps/{id}/paid-compare compare_paid

Compare one app's ads at home against a target market

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`to`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`from`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Home market

Label Compare

GET /api/labels/compare label_compare

Label differences between two markets - share of each answer per label for listings, screenshots, ads or posts, largest differences first, with item ids

Name	In	Required	Type	Description
`item_type`	query	yes	listing \| screenshot \| ad \| post	What was labelled
`from`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Reference market
`to`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Market compared with it
`niche`	query		games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.
`store`	query		ios \| play	Listings and screenshots: ios (default) or play
`chart`	query		free \| paid \| grossing	Listings and screenshots with a niche: chart type (default free)
`top`	query		integer	Listings and screenshots with a niche: the top N of the chart (1-100, default 100)

Market

GET /api/agent/market agent_market

One market and genre - what wins there, optionally next to a reference app or a home market, as a digest

Name	In	Required	Type	Description
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`genre`	query	yes	string	Genre in plain words or a slug
`like`	query		string	Reference app: name, id or store URL
`vs`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl	Home market to compare against
`store`	query		ios \| play	ios or play
`focus`	query		overview \| brand \| paid \| organic \| pricing \| language \| launch	overview (default) or one part in depth
`platform`	query		string	Paid/Organic platform filter
`format`	query		string	Creative format filter
`cursor`	query		string	Cursor from a previous answer

History

Listing History

GET /api/apps/{id}/history listing_history

History of an app's store listing - title, description, screenshots and price changes over time

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`market`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`store`	query		ios \| play	ios (default) or play

Chart History

GET /api/chart-history chart_history

Daily chart rank history for an app or a market and niche

Name	In	Type	Description
`app`	query	string
`market`	query	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`niche`	query	games \| education \| health-fitness \| finance \| productivity \| lifestyle \| business \| weather \| utilities \| travel \| sports \| social-networking \| reference \| photo-video \| news \| navigation \| music \| entertainment \| books \| medical \| magazines-newspapers \| catalogs \| food-drink \| shopping \| stickers \| developer-tools \| graphics-design \| games-action \| games-adventure \| games-casual \| games-board \| games-card \| games-casino \| games-dice \| games-educational \| games-family \| games-music \| games-puzzle \| games-racing \| games-role-playing \| games-simulation \| games-sports \| games-strategy \| games-trivia \| games-word \| games-arcade \| communication \| dating \| video-players \| personalization \| auto-vehicles \| beauty \| comics \| events \| house-home \| parenting	Niche or any collected genre slug (GET /api/meta genres)
`store`	query	ios \| play	ios (default) or play
`chart`	query	free \| paid \| grossing	Chart type: top free (default), top paid or top grossing
`days`	query	integer	Look-back window in days
`limit`	query	integer
`offset`	query	integer

Backfill App

POST /api/apps/{id}/backfill backfill_app

Trigger or check historical backfill for an app across approved sources

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id

Export History

GET /api/export/history export_history

Export full history of listing snapshots, ads and posts as streaming JSONL with evidence fields

Name	In	Required	Type	Description
`app`	query	yes	string

Organic

Organic Posts

GET /api/organic organic_posts

Creator and social posts about an app or niche in a market, with publish dates and views

Name	In	Type	Description
`market`	query	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`app`	query	string
`niche`	query	games \| education \| health-fitness \| finance \| productivity \| lifestyle
`source`	query	string	Channel: youtube, tiktok, instagram or x
`since`	query	string
`sort`	query	views \| recent	views (default) or recent
`brand_account`	query	boolean	true: posts from the app's own account (Instagram Business Discovery); false: creator and hashtag posts. Omit for both.
`limit`	query	integer
`offset`	query	integer

Paid

Paid Ads

GET /api/paid paid_ads

Ads running in a market, for an app or a niche, with start and stop dates and how long they ran

Name	In	Type	Description
`market`	query	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`app`	query	string
`niche`	query	games \| education \| health-fitness \| finance \| productivity \| lifestyle
`source`	query	meta_ad_library \| tiktok_creative_center \| tiktok_commercial_content \| google_ads_transparency \| linkedin_ad_library
`active`	query	boolean	Only ads still running
`minDays`	query	integer	Ran at least this many days
`lang`	query	string	Language (es) or variant (es-MX)
`sort`	query	longest \| recent	longest (default) or recent
`limit`	query	integer
`offset`	query	integer

Paid Summary

GET /api/paid/summary paid_summary

Summary of ads in a market - advertisers, counts and longest running ads

Name	In	Type
`market`	query	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`app`	query	string
`niche`	query	games \| education \| health-fitness \| finance \| productivity \| lifestyle

Reviews

App Reviews

GET /api/apps/{id}/reviews app_reviews

Store reviews for an app in one market, with dates, ratings, version and language

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`market`	query		gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl
`store`	query		ios \| play	ios (default) or play
`limit`	query		integer
`cursor`	query		string	Paging cursor from the previous response

Review Summary

GET /api/apps/{id}/reviews/summary review_summary

Summary of an app's reviews in one market - rating mix, languages and recent themes

Name	In	Required	Type	Description
`id`	path	yes	string	Path parameter id
`market`	query	yes	gb \| us \| es \| mx \| ar \| br \| de \| fr \| jp \| kr \| ca \| au \| tw \| it \| nl \| tr \| sa \| in \| ca-fr \| hk \| th \| id \| ch \| pl \| se \| ae \| vn \| ph \| pt \| at \| co \| cl

Search

Search Apps

GET /api/search search_apps

Search apps already in the library by name or developer, with where each one charts

Name	In	Required	Type	Description
`q`	query	yes	string	App name or developer
`store`	query		ios \| play	ios (default) or play
`limit`	query		integer	Page size
`offset`	query		integer	Skip this many results

Search App Store

GET /api/store-search search_store

Live App Store search for any app, not only charting ones, to get its id

Name	In	Required	Type	Description
`q`	query	yes	string	Search term

API reference

#Account

#Library Metadata

#Track App

#Account Usage

#Request Coverage

#Save Item

#List Collections

#Get Collection

#Add Collection Note

#Create Watch

#List Watches

#Delete Watch

#Watch Events

#Workspace

#Analysis

#Explain Listing Differences

#Explain Paid

#Brand Name Check

#Translate

#Describe Video

#Visual Brief

#i18n Readiness Rules Catalogue

#Store and Retrieve i18n Reports

#Store and Retrieve i18n Reports

#Market Glossary

#Market Glossary

#Variant Lint

#Variant Lint

#Listing Check

#Price Points

#Market Launch Checklist

#Label Profile

#Language Fit

#App

#Get App

#Screenshot Gallery

#App

#Brief

#Market Brief

#B2B Market Checklist

#B2B Market Checklist

#Market Entry Report

#Market Entry Narrative

#Market Take

#Check

#Chart

#Top Apps

#Compare

#Compare Markets

#Compare Paid

#Label Compare

#Market

#History

#Listing History

#Chart History

#Backfill App

#Export History

#Organic

#Organic Posts

#Paid

#Paid Ads

#Paid Summary

#Reviews

#App Reviews

#Review Summary

#Search

#Search Apps

#Search App Store

Account

Library Metadata

Track App

Account Usage

Request Coverage

Save Item

List Collections

Get Collection

Add Collection Note

Create Watch

List Watches

Delete Watch

Watch Events

Workspace

Analysis

Explain Listing Differences

Explain Paid

Brand Name Check

Translate

Describe Video

Visual Brief

i18n Readiness Rules Catalogue

Store and Retrieve i18n Reports

Store and Retrieve i18n Reports

Market Glossary

Market Glossary

Variant Lint

Variant Lint

Listing Check

Price Points

Market Launch Checklist

Label Profile

Language Fit

App

Get App

Screenshot Gallery

App

Brief

Market Brief

B2B Market Checklist

B2B Market Checklist

Market Entry Report

Market Entry Narrative

Market Take

Check

Chart

Top Apps

Compare

Compare Markets

Compare Paid

Label Compare

Market

History

Listing History

Chart History

Backfill App

Export History

Organic

Organic Posts

Paid

Paid Ads

Paid Summary

Reviews

App Reviews

Review Summary

Search

Search Apps

Search App Store