{"openapi":"3.1.0","info":{"title":"ASORadar API","description":"App Reviews API for App Store and Google Play","termsOfService":"https://asoradar.com/help/terms","contact":{"name":"Get the access_key","url":"https://asoradar.com/tokens"},"license":{"name":"Pricing","url":"https://asoradar.com/pricing"},"version":"2.55.0"},"paths":{"/a1/reviews":{"get":{"tags":["App Store / Reviews"],"summary":"List App Store user reviews","description":"Returns recent App Store reviews for an app. Cache-first: serves from local store when fresh, falls back to scraper-node walking newest pages until the watermark or budget is hit. `total` counts matching rows in the locally backfilled slice — NOT the store-wide review count; check `cache.window_covered` ({from, to, hours}) and `cache.reviews_per_day_in_slice` before comparing volumes across apps or stores. Counts from different endpoints may come from different snapshots — compare their `fetched_at` values.","operationId":"get_reviews_a1_reviews_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"rating","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"since_review_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since Review Id"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"search_mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(substring|word)$","description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)","default":"substring","title":"Search Mode"},"description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresh"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"default":200,"title":"Count"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/reviews/by-version":{"get":{"tags":["App Store / Reviews"],"summary":"List App Store reviews filtered by app version","description":"Returns recent App Store reviews filtered by `version`. Same shape as `/a1/reviews` (`{items, total, cache, ...}`). Cache-first: serves from local store; refresh under the per-app lock if stale or `fresh=true`. Other filters (`rating`, `since`, `until`, `search`) compose with the version filter.","operationId":"get_reviews_by_version_a1_reviews_by_version_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"App version to filter by","title":"Version"},"description":"App version to filter by"},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"rating","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"since_review_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since Review Id"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"search_mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(substring|word)$","description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)","default":"substring","title":"Search Mode"},"description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresh"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"default":200,"title":"Count"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/app/by-name":{"get":{"tags":["App Store / Metadata"],"summary":"Resolve an App Store app by name","description":"Composite endpoint: runs an App Store search with `num=1` and returns the full payload of the top match. Billed as two scraper calls (search + app). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_app_by_name_a1_app_by_name_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"App name search term","title":"Name"},"description":"App name search term"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get App By Name A1 App By Name Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/app/{app_id}":{"get":{"tags":["App Store / Metadata"],"summary":"Get full App Store app payload","description":"Returns the full App Store metadata for the given numeric app id. Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_app_a1_app__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get App A1 App  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/search":{"get":{"tags":["App Store / Discovery"],"summary":"Search App Store apps","description":"Live App Store search by term. Cached for 5 minutes to dedup identical queries; pass `?fresh=true` to bypass.","operationId":"get_search_a1_search_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Term"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Num"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Search A1 Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/suggest":{"get":{"tags":["App Store / Discovery"],"summary":"App Store autocomplete suggestions","description":"Returns App Store search autocomplete suggestions for a term. Cached for 5 minutes; pass `?fresh=true` to bypass.","operationId":"get_suggest_a1_suggest_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Term"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Suggest A1 Suggest Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/list":{"get":{"tags":["App Store / Discovery"],"summary":"App Store top-chart list","description":"Returns the App Store top chart for a given collection and/or category. Hard-capped at 200 items by the upstream API. Cached for 1h; pass `?fresh=true` to bypass.","operationId":"get_list_a1_list_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"Chart collection — constant or raw RSS id, both accepted: TOP_FREE_IOS (topfreeapplications), TOP_PAID_IOS, TOP_GROSSING_IOS, NEW_IOS, NEW_FREE_IOS, NEW_PAID_IOS, TOP_FREE_IPAD, TOP_PAID_IPAD, TOP_GROSSING_IPAD, TOP_MAC, TOP_FREE_MAC, TOP_PAID_MAC, TOP_GROSSING_MAC. Default: TOP_FREE_IOS.","default":"","title":"Collection"},"description":"Chart collection — constant or raw RSS id, both accepted: TOP_FREE_IOS (topfreeapplications), TOP_PAID_IOS, TOP_GROSSING_IOS, NEW_IOS, NEW_FREE_IOS, NEW_PAID_IOS, TOP_FREE_IPAD, TOP_PAID_IPAD, TOP_GROSSING_IPAD, TOP_MAC, TOP_FREE_MAC, TOP_PAID_MAC, TOP_GROSSING_MAC. Default: TOP_FREE_IOS."},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"iTunes category id (optional)","default":"","title":"Category"},"description":"iTunes category id (optional)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Num"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get List A1 List Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/similar/{app_id}":{"get":{"tags":["App Store / Discovery"],"summary":"Apps similar to a given App Store app","description":"Returns a list of apps that the App Store flags as similar to the given app. Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_similar_a1_similar__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Similar A1 Similar  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/developer/{dev_id}":{"get":{"tags":["App Store / Discovery"],"summary":"Developer portfolio on App Store","description":"Returns the apps published by an App Store developer (artistId). Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_developer_a1_developer__dev_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dev_id","in":"path","required":true,"schema":{"type":"string","description":"Apple developer id (numeric)","title":"Dev Id"},"description":"Apple developer id (numeric)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Developer A1 Developer  Dev Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/categories":{"get":{"tags":["App Store / Discovery"],"summary":"App Store category catalog","description":"Returns the static map of App Store category and collection identifiers. Cached for 1h; pass `?fresh=true` to bypass.","operationId":"get_categories_a1_categories_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Categories A1 Categories Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/version-history/{app_id}":{"get":{"tags":["App Store / Metadata"],"summary":"App Store version history","description":"Returns the per-version release notes timeline for an App Store app. Cached for 1h; pass `?fresh=true` to bypass. Cache misses also append any unseen versions to the structured `app_versions` history table.","operationId":"get_version_history_a1_version_history__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Version History A1 Version History  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/version-history/{app_id}/diff":{"get":{"tags":["App Store / Metadata","App Store / AI Agents"],"summary":"Diff App Store release notes between consecutive versions","description":"Composite (Tier 1): returns a deterministic line-level diff of release notes between consecutive App Store versions of an app. Reads the local `app_versions` history (populated by `/a1/version-history` cache misses) — does NOT call the scraper. Optional `from`/`to` ISO-8601 timestamps filter the release window. Each entry shows added/removed lines vs the previous version in the window; the first entry counts all its lines as added. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h.","operationId":"get_version_history_diff_a1_version_history__app_id__diff_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest release timestamp (ISO-8601, inclusive)","title":"From"},"description":"Earliest release timestamp (ISO-8601, inclusive)"},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Latest release timestamp (ISO-8601, inclusive)","title":"To"},"description":"Latest release timestamp (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/metadata-diff/{app_id}":{"get":{"tags":["App Store / Metadata","App Store / AI Agents"],"summary":"Diff App Store metadata across cached snapshots","description":"Composite (Tier 1): returns a timeline of changes to App Store metadata (title, subtitle, description, version, releaseNotes, icon, screenshots, ipadScreenshots) across the locally cached snapshot history of `/a1/app/{app_id}`. Reads from `app_snapshots` — does NOT trigger a scraper call. Optional `since` (ISO-8601) trims the lookback window. Each timeline entry shows added/removed list items or before/after scalar values vs the previous snapshot; entries with no changes are dropped. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 1h.","operationId":"get_metadata_diff_a1_metadata_diff__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)","title":"Since"},"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/privacy/{app_id}":{"get":{"tags":["App Store / Metadata"],"summary":"App Store privacy disclosures","description":"Returns App Store privacy types, data categories, and purposes for an app. Cached for 7 days; pass `?fresh=true` to bypass.","operationId":"get_privacy_a1_privacy__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Privacy A1 Privacy  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/privacy/{app_id}/diff":{"get":{"tags":["App Store / Metadata","App Store / AI Agents"],"summary":"Diff App Store privacy disclosures across cached snapshots","description":"Composite (Tier 1): returns a timeline of additions/removals to App Store privacy disclosures (`privacyTypes`) across the locally cached snapshot history of `/a1/privacy/{app_id}`. Reads from `app_snapshots` — does NOT trigger a scraper call. Optional `since` (ISO-8601) trims the lookback window. Each entry shows the structured items added/removed vs the previous snapshot; entries with no changes are dropped. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h.","operationId":"get_privacy_diff_a1_privacy__app_id__diff_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)","title":"Since"},"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/ratings/{app_id}":{"get":{"tags":["App Store / Metadata"],"summary":"App Store ratings histogram","description":"Returns total ratings count and the 1-5 star histogram for an App Store app. Cached for 30 minutes; pass `?fresh=true` to bypass.","operationId":"get_ratings_a1_ratings__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Ratings A1 Ratings  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/clone-brief/{app_id}":{"get":{"tags":["App Store / Metadata","App Store / AI Agents"],"summary":"App Store clone-brief composite for AI agents","description":"Composite (Tier 1): one-shot brief for an AI agent planning to clone-and-improve an App Store app. Fans out 5 parallel scraper calls (app metadata, top reviews, privacy disclosures, similar apps, ratings histogram) under independent per-component timeouts. Returns the Tier 1 envelope `ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`; `data` carries explicit sections (`app`, `top_reviews`, `classified_complaints`, `sentiment_coverage`, `sentiment_sample_size`, `data_collection`, `similar_apps`, `rating_histogram`). `classified_complaints` is `null` until the Tier 1 sentiment system is enabled (and below the configured coverage threshold). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_clone_brief_a1_clone_brief__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/niche-scan":{"get":{"tags":["App Store / Discovery","App Store / AI Agents"],"summary":"App Store niche-saturation scan composite for AI agents","description":"Composite (Tier 1): pulls a top-chart slice for the requested `collection`/`category`/`country` (default `num=50`, max 100), fans out per-app metadata fetches under the global Redis semaphore + per-request asyncio cap, then aggregates rating, review-count, release-recency, and developer-share statistics over the result set. When the global throttle saturates, per-app fetches fall back to the freshest cached snapshot regardless of TTL; `freshness.stale_count` reports how many apps were served from stale cache. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_niche_scan_a1_niche_scan_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"iTunes collection id (optional)","default":"","title":"Collection"},"description":"iTunes collection id (optional)"},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"iTunes category id (optional)","default":"","title":"Category"},"description":"iTunes category id (optional)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Top-chart slice size","default":50,"title":"Num"},"description":"Top-chart slice size"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/keyword-rank":{"get":{"tags":["App Store / Discovery","App Store / AI Agents"],"summary":"App Store keyword rank check composite for AI agents","description":"Composite (Tier 1): checks where an app ranks in App Store search for up to 10 keywords in one call. Fans out one search per term (reusing the `/search` cache), returns the 1-based `rank` per term (`null` when outside the checked depth), the top-3 `leaders` per term, and a `summary` with the best-ranking keyword. Rank tracking only — search volume/difficulty is out of scope by design. Bills one unit per term. Cached for 5 minutes; pass `?fresh=true` to bypass.","operationId":"get_keyword_rank_a1_keyword_rank_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Numeric App Store id or bundle id to look for","title":"App Id"},"description":"Numeric App Store id or bundle id to look for"},{"name":"terms","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Comma-separated keywords, max 10 per call","title":"Terms"},"description":"Comma-separated keywords, max 10 per call"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Search depth per term","default":100,"title":"Num"},"description":"Search depth per term"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/keyword-ideas":{"get":{"tags":["App Store / Discovery","App Store / AI Agents"],"summary":"App Store keyword ideas composite for AI agents","description":"Composite (Tier 1): expands a seed keyword into real App Store search phrases via autocomplete. Default is one suggest call; `expand=true` walks the classic a-z suggest tree (26 extra calls, billed accordingly) and merges the deduped pool with per-idea `sources`. Discovery only — no volume/difficulty scores. Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_keyword_ideas_a1_keyword_ideas_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Seed keyword","title":"Term"},"description":"Seed keyword"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"expand","in":"query","required":false,"schema":{"type":"boolean","description":"Walk the a-z autocomplete tree (26 extra calls)","default":false,"title":"Expand"},"description":"Walk the a-z autocomplete tree (26 extra calls)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/keyword-brief":{"get":{"tags":["App Store / Discovery","App Store / AI Agents"],"summary":"App Store keyword opportunity brief composite for AI agents","description":"Composite (Tier 1): a one-call ASO opportunity brief for an app, built only from our own data (no volume/difficulty — that is Apple Search Ads territory). From up to 5 seed keywords it expands autocomplete, strips app-title noise, checks where the app ranks for each real phrase, and returns `opportunities` (real-demand keywords the app doesn't own), `owned` (top-10 keywords), and `competitors` (apps that keep leading the searches). Bills one unit per seed (suggest) plus one per candidate phrase (search). Cached 1h; pass `?fresh=true` to bypass.","operationId":"get_keyword_brief_a1_keyword_brief_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Target app id","title":"App Id"},"description":"Target app id"},{"name":"seeds","in":"query","required":true,"schema":{"type":"string","description":"1-5 comma-separated seed keywords for the app's niche","title":"Seeds"},"description":"1-5 comma-separated seed keywords for the app's niche"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":10,"description":"Search depth per keyword","default":50,"title":"Num"},"description":"Search depth per keyword"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/developer/{dev_id}/portfolio-stats":{"get":{"tags":["App Store / Discovery","App Store / AI Agents"],"summary":"App Store developer portfolio statistics composite","description":"Composite (Tier 1): pulls a developer's App Store catalogue, fans out per-app metadata fetches under the global Redis semaphore + per-request asyncio cap, then aggregates studio-level statistics — average rating, total reviews, release cadence (average gap in days between consecutive releases), oldest/newest release, score distribution, genre distribution. When the global throttle saturates, per-app fetches fall back to the freshest cached snapshot regardless of TTL; `freshness.stale_count` reports how many apps were served from stale cache. Apple does not expose installs so `avg_installs`/`total_installs` are `null`. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_portfolio_stats_a1_developer__dev_id__portfolio_stats_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dev_id","in":"path","required":true,"schema":{"type":"string","description":"Apple developer id (numeric)","title":"Dev Id"},"description":"Apple developer id (numeric)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Cap on apps from the developer portfolio","default":50,"title":"Num"},"description":"Cap on apps from the developer portfolio"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a1/reviews/sentiment/{app_id}":{"get":{"tags":["App Store / Reviews","App Store / AI Agents"],"summary":"App Store sentiment + topic clustering aggregate","description":"Composite (Tier 1): aggregates LLM-classified sentiment and topic clusters for the App Store reviews of an app. Reads locally from `reviews` ⋈ `reviews_sentiment` (single-shard, co-located by Task 10) — does NOT trigger a scraper or LLM call. Returns sentiment distribution (4 classes: `positive`/`negative`/`neutral`/`mixed`), per-version delta, top topics (up to 20 by frequency), `total_classified`, `total_reviews`, `coverage_pct` (classified/total), and `last_processed_at` (max ``processed_at`` from the batcher). When coverage is thin the payload carries `warnings[]` (`classification_pending` | `low_coverage`) — an empty distribution does NOT mean the app has no signal. Wrapped in the Tier 1 composite envelope. Cached for 1h; `?fresh=true` bypasses the cache AND queues unclassified reviews for priority LLM classification (2h cooldown per app) — the response then carries `classification.status` (`queued`/`recently_queued`/`complete`); re-check after the next batch run.","operationId":"get_reviews_sentiment_a1_reviews_sentiment__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Apple numeric app id","title":"App Id"},"description":"Apple numeric app id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/reviews":{"get":{"tags":["Google Play / Reviews"],"summary":"List Google Play user reviews","description":"Returns recent Google Play reviews for an app. Cache-first: serves from local store when fresh, falls back to scraper-node walking newest pages until the watermark or budget is hit. `total` counts matching rows in the locally backfilled slice — NOT the store-wide review count; check `cache.window_covered` ({from, to, hours}) and `cache.reviews_per_day_in_slice` before comparing volumes across apps or stores. Counts from different endpoints may come from different snapshots — compare their `fetched_at` values.","operationId":"get_reviews_g1_reviews_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"en","title":"Lang"}},{"name":"rating","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"since_review_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since Review Id"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"search_mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(substring|word)$","description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)","default":"substring","title":"Search Mode"},"description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresh"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"default":200,"title":"Count"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/reviews/by-version":{"get":{"tags":["Google Play / Reviews"],"summary":"List Google Play reviews filtered by app version","description":"Returns recent Google Play reviews filtered by `version`. Same shape as `/g1/reviews` (`{items, total, cache, ...}`). Cache-first: serves from local store; refresh under the per-app lock if stale or `fresh=true`. Other filters (`rating`, `since`, `until`, `search`) compose with the version filter.","operationId":"get_reviews_by_version_g1_reviews_by_version_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"version","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"App version to filter by","title":"Version"},"description":"App version to filter by"},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"en","title":"Lang"}},{"name":"rating","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}},{"name":"since_review_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since Review Id"}},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Until"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"name":"search_mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(substring|word)$","description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)","default":"substring","title":"Search Mode"},"description":"word = whole-word match (PG word boundaries; 'fee' no longer matches 'feels') — recommended for agents; substring = legacy ILIKE containment (default for backward compatibility)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresh"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"default":200,"title":"Count"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/app/by-name":{"get":{"tags":["Google Play / Metadata"],"summary":"Resolve a Google Play app by name","description":"Composite endpoint: runs a Google Play search with `num=1` and returns the full payload of the top match. Billed as two scraper calls (search + app). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_app_by_name_g1_app_by_name_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"App name search term","title":"Name"},"description":"App name search term"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get App By Name G1 App By Name Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/app/{app_id}":{"get":{"tags":["Google Play / Metadata"],"summary":"Get full Google Play app payload","description":"Returns the full Google Play metadata for the given reverse-domain package id. Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_app_g1_app__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id (reverse-domain)","title":"App Id"},"description":"Google Play package id (reverse-domain)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get App G1 App  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/search":{"get":{"tags":["Google Play / Discovery"],"summary":"Search Google Play apps","description":"Live Google Play search by term. Cached for 5 minutes to dedup identical queries; pass `?fresh=true` to bypass.","operationId":"get_search_g1_search_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Term"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":250,"minimum":1,"default":50,"title":"Num"}},{"name":"price","in":"query","required":false,"schema":{"type":"string","description":"all|free|paid (optional)","default":"","title":"Price"},"description":"all|free|paid (optional)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Search G1 Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/suggest":{"get":{"tags":["Google Play / Discovery"],"summary":"Google Play autocomplete suggestions","description":"Returns Google Play search autocomplete suggestions for a term. Cached for 5 minutes; pass `?fresh=true` to bypass.","operationId":"get_suggest_g1_suggest_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Term"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Suggest G1 Suggest Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/list":{"get":{"tags":["Google Play / Discovery"],"summary":"Google Play top-chart list","description":"Returns the Google Play top chart for a given collection and category. Up to ~660 items depending on the collection. Cached for 1h; pass `?fresh=true` to bypass.","operationId":"get_list_g1_list_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"Chart collection — constant or raw id, both accepted: TOP_FREE (topselling_free), TOP_PAID (topselling_paid), GROSSING (topgrossing). Default: TOP_FREE.","default":"TOP_FREE","title":"Collection"},"description":"Chart collection — constant or raw id, both accepted: TOP_FREE (topselling_free), TOP_PAID (topselling_paid), GROSSING (topgrossing). Default: TOP_FREE."},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"Google Play category id (optional)","default":"","title":"Category"},"description":"Google Play category id (optional)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":660,"minimum":1,"default":100,"title":"Num"}},{"name":"age","in":"query","required":false,"schema":{"type":"string","description":"FIVE_UNDER|SIX_EIGHT|NINE_UP (optional)","default":"","title":"Age"},"description":"FIVE_UNDER|SIX_EIGHT|NINE_UP (optional)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get List G1 List Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/similar/{app_id}":{"get":{"tags":["Google Play / Discovery"],"summary":"Apps similar to a given Google Play app","description":"Returns a list of apps that Google Play flags as similar to the given app. Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_similar_g1_similar__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Similar G1 Similar  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/developer/{dev_id}":{"get":{"tags":["Google Play / Discovery"],"summary":"Developer portfolio on Google Play","description":"Returns the apps published by a Google Play developer. Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_developer_g1_developer__dev_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dev_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play developer id","title":"Dev Id"},"description":"Google Play developer id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":1,"default":60,"title":"Num"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Developer G1 Developer  Dev Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/categories":{"get":{"tags":["Google Play / Discovery"],"summary":"Google Play category catalog","description":"Returns the static map of Google Play category identifiers. Cached for 1h; pass `?fresh=true` to bypass.","operationId":"get_categories_g1_categories_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Categories G1 Categories Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/permissions/{app_id}":{"get":{"tags":["Google Play / Metadata"],"summary":"Google Play app permissions","description":"Returns the list of Android permissions declared by a Google Play app. Cached for 7 days; pass `?fresh=true` to bypass.","operationId":"get_permissions_g1_permissions__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"short","in":"query","required":false,"schema":{"type":"boolean","description":"Return short-form permissions list","default":false,"title":"Short"},"description":"Return short-form permissions list"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Permissions G1 Permissions  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/datasafety/{app_id}":{"get":{"tags":["Google Play / Metadata"],"summary":"Google Play Data Safety section","description":"Returns the Data Safety disclosures (data shared, data collected, security practices). Cached for 7 days; pass `?fresh=true` to bypass.","operationId":"get_datasafety_g1_datasafety__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","title":"App Id"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and refetch","default":false,"title":"Fresh"},"description":"Bypass cache and refetch"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Datasafety G1 Datasafety  App Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/metadata-diff/{app_id}":{"get":{"tags":["Google Play / Metadata","Google Play / AI Agents"],"summary":"Diff Google Play metadata across cached snapshots","description":"Composite (Tier 1): returns a timeline of changes to Google Play metadata (title, summary, description, version, recentChanges, icon, headerImage, screenshots) across the locally cached snapshot history of `/g1/app/{app_id}`. Reads from `app_snapshots` — does NOT trigger a scraper call. Optional `since` (ISO-8601) trims the lookback window. Each timeline entry shows added/removed list items or before/after scalar values vs the previous snapshot; entries with no changes are dropped. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 1h.","operationId":"get_metadata_diff_g1_metadata_diff__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id","title":"App Id"},"description":"Google Play package id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)","title":"Since"},"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/datasafety/{app_id}/diff":{"get":{"tags":["Google Play / Metadata","Google Play / AI Agents"],"summary":"Diff Google Play Data Safety across cached snapshots","description":"Composite (Tier 1): returns a timeline of additions/removals to the Google Play Data Safety section (`sharedData`, `collectedData`, `securityPractices`) across the locally cached snapshot history of `/g1/datasafety/{app_id}`. Reads from `app_snapshots` — does NOT trigger a scraper call. Optional `since` (ISO-8601) trims the lookback window. Each entry shows the structured items added/removed vs the previous snapshot; entries with no changes are dropped. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h.","operationId":"get_datasafety_diff_g1_datasafety__app_id__diff_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id","title":"App Id"},"description":"Google Play package id"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)","title":"Since"},"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/permissions/{app_id}/diff":{"get":{"tags":["Google Play / Metadata","Google Play / AI Agents"],"summary":"Diff Google Play permissions across cached snapshots","description":"Composite (Tier 1): returns a timeline of additions/removals to the Google Play permissions list across the locally cached snapshot history of `/g1/permissions/{app_id}`. Reads from `app_snapshots` — does NOT trigger a scraper call. The `short` flag must match the form requested when the snapshots were written (short-form and full-form histories are independent). Optional `since` (ISO-8601) trims the lookback window. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h.","operationId":"get_permissions_diff_g1_permissions__app_id__diff_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id","title":"App Id"},"description":"Google Play package id"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"short","in":"query","required":false,"schema":{"type":"boolean","description":"Match the short-form snapshots","default":false,"title":"Short"},"description":"Match the short-form snapshots"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)","title":"Since"},"description":"Earliest snapshot fetched_at (ISO-8601, inclusive)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/clone-brief/{app_id}":{"get":{"tags":["Google Play / Metadata","Google Play / AI Agents"],"summary":"Google Play clone-brief composite for AI agents","description":"Composite (Tier 1): one-shot brief for an AI agent planning to clone-and-improve a Google Play app. Fans out 4 parallel scraper calls (app metadata, top reviews, permissions, similar apps) under independent per-component timeouts. The ratings histogram is extracted from the app payload (no separate Google endpoint). Returns the Tier 1 envelope `ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`; `data` carries explicit sections (`app`, `top_reviews`, `classified_complaints`, `sentiment_coverage`, `sentiment_sample_size`, `data_collection`, `similar_apps`, `rating_histogram`). `classified_complaints` is `null` until the Tier 1 sentiment system is enabled (and below the configured coverage threshold). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_clone_brief_g1_clone_brief__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id","title":"App Id"},"description":"Google Play package id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/niche-scan":{"get":{"tags":["Google Play / Discovery","Google Play / AI Agents"],"summary":"Google Play niche-saturation scan composite for AI agents","description":"Composite (Tier 1): pulls a Google Play top-chart slice for the requested `collection`/`category`/`country`/`lang` (default `num=50`, max 100), fans out per-app metadata fetches under the global Redis semaphore + per-request asyncio cap, then aggregates rating, review-count, install-count, release-recency, and developer-share statistics. When the global throttle saturates, per-app fetches fall back to the freshest cached snapshot regardless of TTL; `freshness.stale_count` reports how many apps were served from stale cache. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_niche_scan_g1_niche_scan_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"Chart collection — constant or raw id, both accepted: TOP_FREE (topselling_free), TOP_PAID (topselling_paid), GROSSING (topgrossing). Default: TOP_FREE.","default":"TOP_FREE","title":"Collection"},"description":"Chart collection — constant or raw id, both accepted: TOP_FREE (topselling_free), TOP_PAID (topselling_paid), GROSSING (topgrossing). Default: TOP_FREE."},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"Google Play category id (optional)","default":"","title":"Category"},"description":"Google Play category id (optional)"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Top-chart slice size","default":50,"title":"Num"},"description":"Top-chart slice size"},{"name":"age","in":"query","required":false,"schema":{"type":"string","description":"FIVE_UNDER|SIX_EIGHT|NINE_UP (optional)","default":"","title":"Age"},"description":"FIVE_UNDER|SIX_EIGHT|NINE_UP (optional)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/keyword-rank":{"get":{"tags":["Google Play / Discovery","Google Play / AI Agents"],"summary":"Google Play keyword rank check composite for AI agents","description":"Composite (Tier 1): checks where an app ranks in Google Play search for up to 10 keywords in one call. Fans out one search per term (reusing the `/search` cache), returns the 1-based `rank` per term (`null` when outside the checked depth), the top-3 `leaders` per term, and a `summary` with the best-ranking keyword. Rank tracking only - search volume/difficulty is out of scope by design. Bills one unit per term. Cached for 5 minutes; pass `?fresh=true` to bypass.","operationId":"get_keyword_rank_g1_keyword_rank_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Package name to look for","title":"App Id"},"description":"Package name to look for"},{"name":"terms","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Comma-separated keywords, max 10 per call","title":"Terms"},"description":"Comma-separated keywords, max 10 per call"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":250,"minimum":1,"description":"Search depth per term","default":100,"title":"Num"},"description":"Search depth per term"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/keyword-ideas":{"get":{"tags":["Google Play / Discovery","Google Play / AI Agents"],"summary":"Google Play keyword ideas composite for AI agents","description":"Composite (Tier 1): expands a seed keyword into real Google Play search phrases via autocomplete. Default is one suggest call; `expand=true` walks the classic a-z suggest tree (26 extra calls, billed accordingly) and merges the deduped pool with per-idea `sources`. Discovery only - no volume/difficulty scores. Cached for 6h; pass `?fresh=true` to bypass.","operationId":"get_keyword_ideas_g1_keyword_ideas_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Seed keyword","title":"Term"},"description":"Seed keyword"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"expand","in":"query","required":false,"schema":{"type":"boolean","description":"Walk the a-z autocomplete tree (26 extra calls)","default":false,"title":"Expand"},"description":"Walk the a-z autocomplete tree (26 extra calls)"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/keyword-brief":{"get":{"tags":["Google Play / Discovery","Google Play / AI Agents"],"summary":"Google Play keyword opportunity brief composite for AI agents","description":"Composite (Tier 1): a one-call ASO opportunity brief for an app, built only from our own data (no volume/difficulty). From up to 5 seed keywords it expands autocomplete, strips app-title noise, checks where the app ranks for each real phrase, and returns `opportunities` (real-demand keywords the app doesn't own), `owned` (top-10 keywords), and `competitors` (apps that keep leading the searches). Bills one unit per seed (suggest) plus one per candidate phrase (search). Cached 1h; pass `?fresh=true` to bypass.","operationId":"get_keyword_brief_g1_keyword_brief_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Target package name","title":"App Id"},"description":"Target package name"},{"name":"seeds","in":"query","required":true,"schema":{"type":"string","description":"1-5 comma-separated seed keywords for the app's niche","title":"Seeds"},"description":"1-5 comma-separated seed keywords for the app's niche"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":250,"minimum":10,"description":"Search depth per keyword","default":50,"title":"Num"},"description":"Search depth per keyword"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/developer/{dev_id}/portfolio-stats":{"get":{"tags":["Google Play / Discovery","Google Play / AI Agents"],"summary":"Google Play developer portfolio statistics composite","description":"Composite (Tier 1): pulls a developer's Google Play catalogue, fans out per-app metadata fetches under the global Redis semaphore + per-request asyncio cap, then aggregates studio-level statistics — average rating, total reviews, total/average installs, release cadence (average gap in days between consecutive releases), oldest/newest release, score distribution, genre distribution. When the global throttle saturates, per-app fetches fall back to the freshest cached snapshot regardless of TTL; `freshness.stale_count` reports how many apps were served from stale cache. Wrapped in the Tier 1 composite envelope (`ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`). Cached for 24h; pass `?fresh=true` to bypass.","operationId":"get_portfolio_stats_g1_developer__dev_id__portfolio_stats_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dev_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play developer id","title":"Dev Id"},"description":"Google Play developer id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Cap on apps from the developer portfolio","default":50,"title":"Num"},"description":"Cap on apps from the developer portfolio"},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/g1/reviews/sentiment/{app_id}":{"get":{"tags":["Google Play / Reviews","Google Play / AI Agents"],"summary":"Google Play sentiment + topic clustering aggregate","description":"Composite (Tier 1): aggregates LLM-classified sentiment and topic clusters for the Google Play reviews of an app. Reads locally from `reviews` ⋈ `reviews_sentiment` (single-shard, co-located by Task 10) — does NOT trigger a scraper or LLM call. Returns sentiment distribution (4 classes: `positive`/`negative`/`neutral`/`mixed`), per-version delta, top topics (up to 20 by frequency), `total_classified`, `total_reviews`, `coverage_pct` (classified/total), and `last_processed_at` (max ``processed_at`` from the batcher). When coverage is thin the payload carries `warnings[]` (`classification_pending` | `low_coverage`) — an empty distribution does NOT mean the app has no signal. Wrapped in the Tier 1 composite envelope. Cached for 1h; `?fresh=true` bypasses the cache AND queues unclassified reviews for priority LLM classification (2h cooldown per app) — the response then carries `classification.status` (`queued`/`recently_queued`/`complete`); re-check after the next batch run.","operationId":"get_reviews_sentiment_g1_reviews_sentiment__app_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string","description":"Google Play package id","title":"App Id"},"description":"Google Play package id"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass cache and recompute","default":false,"title":"Fresh"},"description":"Bypass cache and recompute"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/startapp/brief":{"get":{"tags":["AI Agents / StartApp"],"summary":"STARTAPP niche brief for AI agents","description":"Composite (Tier 1): turns a niche into a build-brief. Pass either `apps` (3-7 comma-separated `store:app_id` pairs, cross-store OK) or `query` + a single `store` (candidates come from the store's search in relevance order, first `max_apps`). Per app it reads the stored metadata snapshot and classified review-sentiment topics (apps with `classification` of `none`/`pending` carry zero weight in the matrix — ingest reviews via `/reviews` and re-run within the hour), then synthesizes `gap_matrix` (complaint topics ranked by shared pain), `opportunities` (topics hurting 2+ apps), a 0-100 `opportunity_score`, and an `aso` keyword-suggestion block. Returns the Tier 1 envelope `ok`/`partial`/`data`/`errors`/`cached`/`fetched_at`; failed per-app components land in `errors` and are excluded from the matrix. Bills its fan-out: one unit per app + one for `aso` (e.g. 3 apps → 4). `narrative=true` adds a server-side LLM synthesis — `data.narrative` with `positioning`, `mvp_features`, `anti_features`, `differentiation`, `risks` — and bills +10 units ONLY when the synthesis succeeds; on LLM/budget failure the brief still returns and `errors.narrative` explains.","operationId":"get_brief_startapp_brief_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"apps","in":"query","required":false,"schema":{"type":"string","description":"3-7 comma-separated store:app_id pairs, e.g. `apple:389801252,google:com.ynab` (mutually exclusive with `query`)","default":"","title":"Apps"},"description":"3-7 comma-separated store:app_id pairs, e.g. `apple:389801252,google:com.ynab` (mutually exclusive with `query`)"},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Niche search term for candidate discovery (mutually exclusive with `apps`; requires a single `store`)","default":"","title":"Query"},"description":"Niche search term for candidate discovery (mutually exclusive with `apps`; requires a single `store`)"},{"name":"store","in":"query","required":false,"schema":{"type":"string","description":"Candidate store for query mode: `apple` | `google`. Cross-store niches must pass explicit `apps=` pairs.","default":"both","title":"Store"},"description":"Candidate store for query mode: `apple` | `google`. Cross-store niches must pass explicit `apps=` pairs."},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"us","title":"Country"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5,"default":"en","title":"Lang"}},{"name":"max_apps","in":"query","required":false,"schema":{"type":"integer","maximum":7,"minimum":3,"description":"Query-mode candidate count","default":5,"title":"Max Apps"},"description":"Query-mode candidate count"},{"name":"narrative","in":"query","required":false,"schema":{"type":"boolean","description":"Add data.narrative (LLM PRD-prose synthesis); +10 units, billed only on success","default":false,"title":"Narrative"},"description":"Add data.narrative (LLM PRD-prose synthesis); +10 units, billed only on success"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialResponse_dict_str__Any__"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List your subscriptions","operationId":"list__webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SubscriptionOut"},"type":"array","title":"Response List  Webhooks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]},"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","operationId":"create_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCreate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWithSecret"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/webhooks/{sub_id}":{"get":{"tags":["Webhooks"],"summary":"Get one subscription","operationId":"get_one_webhooks__sub_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"integer","title":"Sub Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a subscription","operationId":"delete__webhooks__sub_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"integer","title":"Sub Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/{sub_id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret","operationId":"rotate_webhooks__sub_id__rotate_secret_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"sub_id","in":"path","required":true,"schema":{"type":"integer","title":"Sub Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWithSecret"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PartialResponse_dict_str__Any__":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"True when the core payload is present (some sub-components may have still failed — see `partial`). False only when the route returns 503 with all components dead."},"partial":{"type":"boolean","title":"Partial","description":"True when at least one sub-component failed; the failure details land in `errors`."},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data","description":"Endpoint-specific payload. `null` only when `ok=False`."},"errors":{"additionalProperties":{"type":"string"},"type":"object","title":"Errors","description":"Per-component error map (component key → short error string). Empty when `partial=false`."},"cached":{"type":"boolean","title":"Cached","description":"True when the envelope came from the response cache."},"fetched_at":{"type":"string","title":"Fetched At","description":"ISO-8601 UTC timestamp of when the envelope was produced (cache-hit: when the cached row was originally written)."}},"type":"object","required":["ok","partial","data","cached","fetched_at"],"title":"PartialResponse[dict[str, Any]]","examples":[{"cached":false,"data":{"...":"endpoint-specific payload"},"errors":{},"fetched_at":"2026-05-10T12:34:56+00:00","ok":true,"partial":false},{"cached":true,"data":{"...":"endpoint-specific payload"},"errors":{"similar":"TimeoutError: deadline exceeded"},"fetched_at":"2026-05-10T12:34:56+00:00","ok":true,"partial":true}]},"SubscriptionCreate":{"properties":{"kind":{"type":"string","title":"Kind","description":"one of ['app_changes', 'chart_movement', 'review_keywords', 'keyword_rank']"},"target_url":{"type":"string","title":"Target Url","description":"https callback URL (no private hosts)"},"criteria":{"additionalProperties":true,"type":"object","title":"Criteria","description":"kind-specific match criteria"}},"type":"object","required":["kind","target_url","criteria"],"title":"SubscriptionCreate"},"SubscriptionOut":{"properties":{"id":{"type":"integer","title":"Id"},"kind":{"type":"string","title":"Kind"},"target_url":{"type":"string","title":"Target Url"},"status":{"type":"string","title":"Status"},"criteria":{"additionalProperties":true,"type":"object","title":"Criteria"},"failure_count":{"type":"integer","title":"Failure Count"}},"type":"object","required":["id","kind","target_url","status","criteria","failure_count"],"title":"SubscriptionOut"},"SubscriptionWithSecret":{"properties":{"id":{"type":"integer","title":"Id"},"kind":{"type":"string","title":"Kind"},"target_url":{"type":"string","title":"Target Url"},"status":{"type":"string","title":"Status"},"criteria":{"additionalProperties":true,"type":"object","title":"Criteria"},"failure_count":{"type":"integer","title":"Failure Count"},"secret":{"type":"string","title":"Secret","description":"HMAC signing secret — shown only once"}},"type":"object","required":["id","kind","target_url","status","criteria","failure_count","secret"],"title":"SubscriptionWithSecret"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"x-access-key"}}},"tags":[{"name":"App Store / Reviews","description":"App Store user reviews. Cache-first, watermark-walked from latest."},{"name":"App Store / Metadata","description":"App Store app metadata: full payload, version history, privacy, ratings histogram."},{"name":"App Store / Discovery","description":"App Store discovery surfaces: search, suggest, top-charts, similar, developer portfolio, category catalog."},{"name":"App Store / AI Agents","description":"App Store Tier 1 composite endpoints stitched from multiple primitives for AI-agent workflows (clone-and-improve briefs, niche scans, metadata / privacy / version diffs, portfolio aggregates, review sentiment). All return the partial-response envelope `{ok, partial, data, errors, cached, fetched_at}` — `partial=true` with a populated `errors` map signals that some sub-fetches failed but the core payload is still usable."},{"name":"Google Play / Reviews","description":"Google Play user reviews. Cache-first, watermark-walked from latest."},{"name":"Google Play / Metadata","description":"Google Play app metadata: full payload, permissions, Data Safety section."},{"name":"Google Play / Discovery","description":"Google Play discovery surfaces: search, suggest, top-charts, similar, developer portfolio, category catalog."},{"name":"Google Play / AI Agents","description":"Google Play Tier 1 composite endpoints stitched from multiple primitives for AI-agent workflows (clone-and-improve briefs, niche scans, metadata / privacy / version diffs, portfolio aggregates, review sentiment). All return the partial-response envelope `{ok, partial, data, errors, cached, fetched_at}` — `partial=true` with a populated `errors` map signals that some sub-fetches failed but the core payload is still usable."},{"name":"AI Agents / StartApp","description":"STARTAPP composite: turns a niche — 3-7 competitor apps (explicit cross-store `store:app_id` pairs, or a single-store search query) — into a build-brief. Per-app niche snapshots from stored metadata + classified review-sentiment topics, a complaint gap matrix, an opportunity list, a 0-100 opportunity score, and ASO keyword suggestions. Returns the partial-response envelope `{ok, partial, data, errors, cached, fetched_at}`; bills its fan-out (one unit per app + one for the ASO block)."}],"servers":[{"url":"/api"}]}