Asolytics-Pro/asolytics-app-store-optimization-api / skills/asolytics-api
asolytics-api
VerifiedUse the Asolytics Public API for ASO research and automation. Trigger this skill when the agent needs to query app metadata, availability, versions, installs, revenue, rankings, keyword metrics, live search results, forced ranking re-checks, recommended keywords, tracked keywords, tracking folders, competitors, projects (own and shared), per-country keyword counts, balance, subscription/plan limits, or store charts from Asolytics. Also use it when a user wants curl examples, lightweight integrations, or repeatable reporting workflows against the Asolytics API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| VERSION | other | 6 B |
| agents/openai.yaml | config | 289 B |
| references/api-overview.md | markdown | 5.2 KB |
| references/endpoints.md | markdown | 28.9 KB |
| references/openapi.json | config | 219.7 KB |
| scripts/sync_openapi.py | script | 6.3 KB |
| scripts/update.shexecutable | script | 2.4 KB |
references/openapi.json
View on GitHub{
"openapi": "3.0.0",
"info": {
"title": "Asolytics Public API",
"description": "> **Alpha version.** This API is in active development. Endpoint shapes, parameters, response formats and token costs may change without prior notice. Pin against stable contracts in your own code and watch the changelog before relying on it in production.",
"version": "1.0.0-alpha"
},
"servers": [
{
"url": "https://app.asolytics.pro",
"description": "Main API server"
}
],
"paths": {
"/public-api/v1/applications/metadata": {
"get": {
"tags": [
"Applications"
],
"summary": "Applications metadata",
"description": "Returns the latest text metadata (title, sub_title, description) of the given apps in the requested locales — the same text the store currently shows on each app's listing page. Only locales that actually carry data are emitted; `origin_id`s we don't have indexed are silently absent.<br><br>**Costs:** 10 tokens per returned (app, locale) pair. A request that returns no pairs is free.",
"operationId": "publicApiApplicationsMetadata",
"parameters": [
{
"name": "origin_ids[]",
"in": "query",
"description": "App store origin ids (max 10) — App Store: numeric track ids (e.g. `1234567890`); Google Play: bundle ids (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 10
},
"example": [
"1234567890",
"9876543210"
]
},
{
"name": "locales[]",
"in": "query",
"description": "Locale codes (max 10). Sourced from `/v1/common-catalogs/locales`.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 35
},
"maxItems": 10
},
"example": [
"en_US",
"de_DE"
]
}
],
"responses": {
"200": {
"description": "Applications metadata grouped by locale.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiApplicationsMetadataViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/metadata/media": {
"get": {
"tags": [
"Applications"
],
"summary": "Applications media",
"description": "Returns the latest screenshots and preview videos of the given apps in the requested locales — the same media the store currently shows on each app's listing page. Each screenshot carries its `device` and 0-based `position` so you can reconstruct the gallery order. Only locales that actually carry media are emitted; `origin_id`s we don't have indexed are silently absent.<br><br>**Costs:** 10 tokens per returned (app, locale) pair. A request that returns no pairs is free.",
"operationId": "publicApiApplicationsMedia",
"parameters": [
{
"name": "origin_ids[]",
"in": "query",
"description": "App store origin ids (max 10) — App Store: numeric track ids (e.g. `1234567890`); Google Play: bundle ids (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 10
},
"example": [
"1234567890",
"9876543210"
]
},
{
"name": "locales[]",
"in": "query",
"description": "Locale codes (max 10). Sourced from `/v1/common-catalogs/locales`.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 35
},
"maxItems": 10
},
"example": [
"en_US",
"de_DE"
]
}
],
"responses": {
"200": {
"description": "Applications media grouped by locale.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiApplicationsMediaViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/availability": {
"get": {
"tags": [
"Applications"
],
"summary": "Applications availability",
"description": "Returns the list of countries in which each of the given apps is currently live in the store. Apps available nowhere (taken down, not yet released, region-blocked everywhere we check) are omitted from the response entirely.<br><br>**Costs:** 10 tokens per app present in the response. A request whose apps are all unavailable returns an empty list and is free.",
"operationId": "publicApiApplicationsAvailability",
"parameters": [
{
"name": "origin_ids[]",
"in": "query",
"description": "App store origin ids (max 10) — App Store: numeric track ids (e.g. `1234567890`); Google Play: bundle ids (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 10
},
"example": [
"1234567890",
"9876543210"
]
}
],
"responses": {
"200": {
"description": "Per-app availability.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiApplicationsAvailabilityViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/versions": {
"get": {
"tags": [
"Applications"
],
"summary": "Application version history",
"description": "Returns the full version history of a single application, newest-first — every release we've captured from the store, with the developer's release notes when present. Returns 404 if the `origin_id` doesn't resolve to a known application; apps with no captured versions return an empty `versions` list (still billed).<br><br>**Costs:** 10 tokens per call.",
"operationId": "publicApiApplicationVersions",
"parameters": [
{
"name": "origin_id",
"in": "query",
"description": "Store origin id of the application — App Store: numeric track id (e.g. `1234567890`); Google Play: bundle id (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "1234567890"
}
],
"responses": {
"200": {
"description": "Version history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiApplicationVersionsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"404": {
"description": "Application not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/installs": {
"get": {
"tags": [
"Applications"
],
"summary": "Application installs history",
"description": "Returns monthly **estimated** installs for a single application across every country we currently track, for each month in the requested range. Values are estimates derived from store signals — not measured installs — and are emitted as `null` for months we couldn't estimate (sparsely-tracked apps, or the most recent month while it's still being computed). Returns 404 if the `origin_id` doesn't resolve to a known application.<br><br>**Costs:** 5 tokens per emitted (country, month) pair carrying a non-null value (`0` counts; `null` does not). Minimum 5 tokens per call — charged even if the entire grid is null.",
"operationId": "publicApiApplicationInstalls",
"parameters": [
{
"name": "origin_id",
"in": "query",
"description": "Store origin id of the application — App Store: numeric track id (e.g. `1234567890`); Google Play: bundle id (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "1234567890"
},
{
"name": "date_from",
"in": "query",
"description": "Inclusive lower month (`Y-m`).",
"required": true,
"schema": {
"type": "string",
"example": "2026-03"
}
},
{
"name": "date_to",
"in": "query",
"description": "Inclusive upper month (`Y-m`).",
"required": true,
"schema": {
"type": "string",
"example": "2026-05"
}
}
],
"responses": {
"200": {
"description": "Per-country installs history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiAppInstallsHistoryViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"404": {
"description": "Application not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/revenue": {
"get": {
"tags": [
"Applications"
],
"summary": "Application revenue history",
"description": "Returns monthly **estimated** revenue (USD) for a single application across every country we currently track, for each month in the requested range. Values are estimates derived from store signals — not measured revenue — and are emitted as `null` for months we couldn't estimate (sparsely-tracked apps, or the most recent month while it's still being computed). Returns 404 if the `origin_id` doesn't resolve to a known application.<br><br>**Costs:** 5 tokens per emitted (country, month) pair carrying a non-null value (`0` counts; `null` does not). Minimum 5 tokens per call — charged even if the entire grid is null.",
"operationId": "publicApiApplicationRevenue",
"parameters": [
{
"name": "origin_id",
"in": "query",
"description": "Store origin id of the application — App Store: numeric track id (e.g. `1234567890`); Google Play: bundle id (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "1234567890"
},
{
"name": "date_from",
"in": "query",
"description": "Inclusive lower month (`Y-m`).",
"required": true,
"schema": {
"type": "string",
"example": "2026-03"
}
},
{
"name": "date_to",
"in": "query",
"description": "Inclusive upper month (`Y-m`).",
"required": true,
"schema": {
"type": "string",
"example": "2026-05"
}
}
],
"responses": {
"200": {
"description": "Per-country revenue history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiAppRevenueHistoryViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"404": {
"description": "Application not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/ranking": {
"get": {
"tags": [
"Applications"
],
"summary": "Application ranking history",
"description": "Returns the ranking history of a single application in the given country, as a paginated flat list of `{date, keyword, position}` rows — one row per scanned (date, keyword) pair the app ranks for, across every keyword we cover (no keyword filter). Supports a position-range filter and sorting by `date`, `position` or `keyword`; pipeline is filter → sort → paginate, so `total` / `total_pages` reflect the filtered universe. The window cannot exceed **7 days** and `date_from` cannot reach further back than the 1st of (current month − 5 months). Returns 404 if the `origin_id` doesn't resolve to a known application; apps with no scans in range return an empty page (still billed the minimum).<br><br>**Costs:** `max(5, ceil(rows_on_page / 20))` tokens — 1 token per started bucket of 20 rows on the returned page, with a floor of 5 charged even on empty responses.",
"operationId": "publicApiApplicationsRanking",
"parameters": [
{
"name": "origin_id",
"in": "query",
"description": "Store origin id of the application — App Store: numeric track id (e.g. `1234567890`); Google Play: bundle id (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "1234567890"
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "date_from",
"in": "query",
"description": "Start of the window. Must be on or after the 1st of (current month − 5 months).",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-12-01"
},
{
"name": "date_to",
"in": "query",
"description": "End of the window. Must be ≤ `date_from` + 7 days.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-12-08"
},
{
"name": "page",
"in": "query",
"description": "1-based page number (default 1).",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "Page size in number of rows (default 100, max 1000).",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1
}
},
{
"name": "sort_by",
"in": "query",
"description": "Field to sort rows by. Allowed: `date`, `position`, `keyword`.",
"required": false,
"schema": {
"type": "string",
"default": "date",
"enum": [
"date",
"position",
"keyword"
]
}
},
{
"name": "sort_order",
"in": "query",
"description": "Sort direction. Defaults to `desc` (newest / worst position first).",
"required": false,
"schema": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc"
]
}
},
{
"name": "filters[position][from]",
"in": "query",
"description": "Inclusive lower bound on `position`. Filtering is applied before pagination.",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"example": 1
},
{
"name": "filters[position][to]",
"in": "query",
"description": "Inclusive upper bound on `position`. Must be ≥ `filters[position][from]`.",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"example": 10
}
],
"responses": {
"200": {
"description": "Per-date ranking history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiApplicationsRankingViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"404": {
"description": "Application not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/applications/ranking/latest-by-keywords": {
"get": {
"tags": [
"Applications"
],
"summary": "Latest ranking position per keyword",
"description": "Returns the app's **latest known** ranking position for each of the requested keywords in the given store/country. Because keywords are parsed on independent schedules, each keyword carries its own `date` — they will not always share the same parse day. Keywords the app does not currently rank for are omitted from the response. The store (Google Play / App Store) is inferred from the `origin_id`.<br><br>**Costs:** 1 token per 30 requested keywords, minimum 5 per call (billed on the request, not the number of rows returned).",
"operationId": "publicApiApplicationsRankingLatestByKeywords",
"parameters": [
{
"name": "origin_id",
"in": "query",
"description": "App store origin id — App Store: numeric track id (e.g. `1234567890`); Google Play: bundle id (e.g. `com.acme.app`).",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "1234567890"
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "keywords[]",
"in": "query",
"description": "Keywords to look up (max 1000, each ≤80 chars).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80
},
"maxItems": 1000
},
"example": [
"fitness app",
"workout tracker"
]
}
],
"responses": {
"200": {
"description": "Latest position per keyword.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/ApplicationsRankingLatestByKeywordsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"404": {
"description": "Application not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/balance": {
"get": {
"tags": [
"Balance"
],
"summary": "Get token balance",
"description": "Returns the user's current public-API token balance along with the last 100 balance transactions (newest first). Each transaction carries its `cause` (the endpoint key that triggered the debit, `null` for system rows like the monthly balance renewal), a signed `amount` (debits are negative), the timestamp, and a pointer back to the originating public-API request (`null` for system rows). The full `cause_details` payload is intentionally not exposed here — treat the list as a quick activity feed, not a complete audit trail.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetBalanceInfo",
"responses": {
"200": {
"description": "Current token balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/ApiTokensBalanceViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"404": {
"description": "No balance found for the user.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiBalanceNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/common-catalogs/countries": {
"get": {
"tags": [
"Common Catalogs"
],
"summary": "List countries",
"description": "Returns the countries we support for the given store — the valid values for every `country_code` parameter elsewhere in the API. The list changes rarely; cache it on your side rather than calling on every request.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetCommonCatalogsCountries",
"parameters": [
{
"name": "store",
"in": "query",
"description": "Store key.",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
}
],
"responses": {
"200": {
"description": "Countries available for the store.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CommonCatalogsCountriesViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/common-catalogs/locales": {
"get": {
"tags": [
"Common Catalogs"
],
"summary": "List locales",
"description": "Returns the locales we support for the given store — the valid values for `locales[]` on the applications/metadata and applications/metadata/media endpoints. The list changes rarely; cache it on your side rather than calling on every request.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetCommonCatalogsLocales",
"parameters": [
{
"name": "store",
"in": "query",
"description": "Store key.",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
}
],
"responses": {
"200": {
"description": "Locales available for the store.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CommonCatalogsLocalesViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/common-catalogs/devices": {
"get": {
"tags": [
"Common Catalogs"
],
"summary": "List devices",
"description": "Returns the device keys we support for the given store — `IPHONE` and `IPAD` on App Store, `MOBILE` on Google Play. These are the valid values for every `device` parameter elsewhere in the API (live-search, store-charts). The list changes rarely; cache it on your side.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetCommonCatalogsDevices",
"parameters": [
{
"name": "store",
"in": "query",
"description": "Store key.",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
}
],
"responses": {
"200": {
"description": "Devices available for the store.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CommonCatalogsDevicesViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/common-catalogs/categories": {
"get": {
"tags": [
"Common Catalogs"
],
"summary": "List categories",
"description": "Returns the store-chart categories for the given store. Each entry's `key` is the value to pass as `category_key` on `/v1/store-charts`. The list changes rarely; cache it on your side.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetCommonCatalogsCategories",
"parameters": [
{
"name": "store",
"in": "query",
"description": "Store key.",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
}
],
"responses": {
"200": {
"description": "Categories for the store.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CommonCatalogsCategoriesViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/common-catalogs/clusters": {
"get": {
"tags": [
"Common Catalogs"
],
"summary": "List clusters",
"description": "Returns the chart clusters for the given store — App Store: top-free / top-paid / top-grossing × iPhone / iPad; Google Play: the equivalent set. Each entry's `key` is the value to pass as `cluster_key` on `/v1/store-charts`. The list changes rarely; cache it on your side.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetCommonCatalogsClusters",
"parameters": [
{
"name": "store",
"in": "query",
"description": "Store key.",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
}
],
"responses": {
"200": {
"description": "Clusters for the store.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CommonCatalogsClustersViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/competitors": {
"get": {
"tags": [
"Competitors"
],
"summary": "List competitors",
"description": "Returns the apps marked as competitors on the project, optionally filtered by state. Competitor state is tracked in the project store's US country (the public API hides per-country state — each app has exactly one state in the list). Each entry carries the competitor app's basic info and its current state (`competitor`, `non_competitor`, `indirect_competitor`).<br><br>**Costs:** 10 tokens per call.",
"operationId": "publicApiListCompetitors",
"parameters": [
{
"name": "project_id",
"in": "query",
"description": "Sourced from `/v1/projects/list`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
},
{
"name": "filters[competitor_state][]",
"in": "query",
"description": "Keep only apps in the given state(s). Defaults to all states.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"competitor",
"non_competitor",
"indirect_competitor"
]
},
"maxItems": 50
}
}
],
"responses": {
"200": {
"description": "Competitor apps.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiCompetitorsListViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/competitors/mark": {
"post": {
"tags": [
"Competitors"
],
"summary": "Mark a competitor",
"description": "Marks an app (by its store `origin_id`) as `competitor`, `non_competitor` or `indirect_competitor` for the project. Idempotent — re-marking with the same state is a no-op; re-marking with a different state moves the app to that state. Returns 404 if the `competitor_origin_id` doesn't resolve to a known app.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiMarkCompetitor",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"competitor_origin_id",
"state"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"competitor_origin_id": {
"description": "Store origin id of the competitor app — App Store: numeric track id; Google Play: bundle id.",
"type": "string",
"maxLength": 128,
"example": "1234567890"
},
"state": {
"type": "string",
"enum": [
"competitor",
"non_competitor",
"indirect_competitor"
],
"example": "competitor"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Marked.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project or application not found.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
},
{
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
]
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/competitors/unmark": {
"post": {
"tags": [
"Competitors"
],
"summary": "Unmark a competitor",
"description": "Removes any competitor mark for the given app (by its store `origin_id`) within the project — the app drops out of the competitors list entirely. Returns 404 if the `competitor_origin_id` doesn't resolve to a known app.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiUnmarkCompetitor",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"competitor_origin_id"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"competitor_origin_id": {
"description": "Store origin id of the competitor app — App Store: numeric track id; Google Play: bundle id.",
"type": "string",
"maxLength": 128,
"example": "1234567890"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Unmarked.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project or application not found.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
},
{
"$ref": "#/components/schemas/PublicApiAppNotFoundSchema"
}
]
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/keywords/ranking/force-recheck": {
"post": {
"tags": [
"Keywords"
],
"summary": "Force a keyword ranking re-check",
"description": "Orders an on-demand re-scan of the store top for the given phrases in a (store, country). The call returns as soon as the re-check is queued — the fresh positions land in our storage a few minutes later and can be read through `/v1/keywords/ranking` or `/v1/applications/ranking`. Supply `webhook.url` to be notified: we POST one message per phrase as soon as its scan is done. Up to 500 phrases per request; duplicates (case-insensitive) are collapsed and billed once.<br><br>**Webhook payload:** `{request: {id}, task: {keyword, country_code, store}, result: {status}}` where `request.id` is the `request.id` of this response. With `webhook.include_positions = true` the result also carries `positions` — the scanned top as `[{position, item: {origin_id}}, …]`, capped at 50 entries; an empty array means the scan found nothing. We ignore the response body and only look at the status code: a non-200 is retried twice with a growing delay, then dropped. Redirects are not followed and the request times out after a few seconds. The callback host must resolve to a public address — private, loopback and link-local targets are rejected and the notice is dropped without retries.<br><br>**Costs**, charged per unique phrase when the re-check is queued (not when it completes): 15 tokens, **+1** with a webhook, **+1** more with `include_positions` — so 15 / 16 / 17 per phrase.",
"operationId": "publicApiForceRecheckKeywordsRanking",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"keywords",
"store",
"country_code"
],
"properties": {
"keywords": {
"description": "Phrases to re-check (max 500, each ≤80 chars).",
"type": "array",
"items": {
"type": "string",
"maxLength": 80
},
"maxItems": 500,
"example": [
"photo editor",
"video maker"
]
},
"store": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"webhook": {
"description": "When present, a POST is sent per completed phrase.",
"properties": {
"url": {
"description": "http/https only.",
"type": "string",
"format": "uri",
"maxLength": 2048,
"example": "https://example.com/asolytics/recheck"
},
"headers": {
"description": "Extra headers sent with the callback (max 10; values are strings). `Host`, `Content-Type` and `Content-Length` cannot be overridden.",
"type": "object",
"example": {
"Authorization": "Bearer xxx"
},
"nullable": true,
"additionalProperties": true
},
"include_positions": {
"description": "Ship the scanned top (`result.positions`) with the callback. Costs 1 extra token per phrase.",
"type": "boolean",
"default": false,
"example": false
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Re-check queued.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiForceRecheckRankingViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"402": {
"description": "Not enough tokens.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/keywords/ranking": {
"get": {
"tags": [
"Keywords"
],
"summary": "Keywords ranking history",
"description": "Returns the top-50 ranking history per keyword for a (store, country) across the requested date range. For each date we emit the apps in their store-shown order with `origin_id` and current title. Dates without a scan are skipped — no gap-filling; apps we couldn't resolve to a known origin are dropped from the positions list. Up to 500 keywords per request; `date_from` cannot reach further back than the start of (current month − 6 months).<br><br>**Costs:** 1 token per (keyword, date) pair returned. A request with no scans in range is free.",
"operationId": "publicApiKeywordsRanking",
"parameters": [
{
"name": "keywords[]",
"in": "query",
"description": "Keyword phrases (max 500, each ≤80 chars).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80
},
"maxItems": 500
},
"example": [
"photo editor",
"video maker"
]
},
{
"name": "store",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
]
},
"example": "APP_STORE"
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "date_from",
"in": "query",
"description": "Start of the window. Must be on or after the start of (current month − 6 months).",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-08-01"
},
{
"name": "date_to",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-08-12"
}
],
"responses": {
"200": {
"description": "Per-keyword top-50 ranking history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiKeywordsRankingViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/keywords/popularity": {
"get": {
"tags": [
"Keywords"
],
"summary": "Keywords popularity history",
"description": "Returns per-keyword popularity history for a (store, country) across the requested date range. For App Store each date carries both `popularity` (raw scan) and `mlp_popularity` (the ML-derived synthetic value that smooths over scan gaps); for Google Play only `mlp_popularity` is returned because GP stores a single popularity column. Only dates with real scans are emitted — no gap-filling, no interpolation. Up to 1000 keywords per request; `date_from` cannot reach further back than the start of (current month − 6 months).<br><br>**Costs:** 1 token per (keyword, date) pair returned. A request with no scans in range is free.",
"operationId": "publicApiKeywordsPopularity",
"parameters": [
{
"name": "keywords[]",
"in": "query",
"description": "Keyword phrases (max 1000, each ≤80 chars).",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80
},
"maxItems": 1000
},
"example": [
"photo editor",
"video maker"
]
},
{
"name": "store",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
]
},
"example": "APP_STORE"
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "date_from",
"in": "query",
"description": "Start of the window. Must be on or after the start of (current month − 6 months).",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-08-01"
},
{
"name": "date_to",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2025-08-12"
}
],
"responses": {
"200": {
"description": "Per-keyword popularity history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiKeywordsPopularityViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/keywords/metrics": {
"get": {
"tags": [
"Keywords"
],
"summary": "Keywords latest metrics",
"description": "Returns a snapshot of one or more latest metrics for up to 250 keywords in a (store, country). Each keyword in the response appears exactly once in the same order and casing as the request; duplicate keywords are deduplicated. Only the requested metrics are present on each keyword object. Metrics that resolve to null (no scan data available) are omitted from the billed pairs but still appear in the response as null.<br><br>**Metric availability by store:**<br>- `popularity` — App Store only (raw scan); Google Play omits the `popularity` field, only `mlp_popularity` is returned.<br>- `max_popularity` — App Store: `year_max_popularity` (raw) and `synthetic_year_max_popularity` (mlp). Google Play: `mlp_max_popularity` only (`all_time_max_popularity`).<br>- `impressions` — App Store: estimated daily impressions derived from both real and synthetic popularity. Google Play: `mlp_impressions` only.<br>- `difficulty` — both stores, single value (no real/mlp split).<br>- `language` — both stores, country-independent, single value.<br><br>**Costs:** 1 token per (keyword, metric) pair where the resolved value is non-null; minimum 1 token per call.",
"operationId": "publicApiKeywordsMetrics",
"parameters": [
{
"name": "keywords[]",
"in": "query",
"description": "Keyword phrases (max 250, each ≤80 chars). Duplicates are deduplicated.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80
},
"maxItems": 250,
"minItems": 1
},
"example": [
"photo editor",
"video maker"
]
},
{
"name": "store",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
]
},
"example": "APP_STORE"
},
{
"name": "country_code",
"in": "query",
"description": "2-letter ISO country code. Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "metrics[]",
"in": "query",
"description": "Metrics to include in the response (min 1, max 50). Allowed values: `popularity`, `max_popularity`, `impressions`, `difficulty`, `language`.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"popularity",
"max_popularity",
"impressions",
"difficulty",
"language"
]
},
"maxItems": 50,
"minItems": 1
},
"example": [
"popularity",
"difficulty"
]
}
],
"responses": {
"200": {
"description": "Per-keyword latest metrics snapshot.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiKeywordsMetricsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/live-search": {
"get": {
"tags": [
"Live Search"
],
"summary": "Live search top 50",
"description": "Returns the live (real-time) top-50 search results for a keyword in the given (store, country, device) — what a user would currently see on the store's search results page, including paid ad placements alongside organic items. On App Store each item carries its `type` (`apps`, `preorder`, `app-bundles`, `developers`, `editorial-items`, `in-apps`, `subscription`); Google Play returns apps only. `is_paid` marks ad placements and `position` is the 1-based rank in the full list with paid items counted. Items we couldn't resolve to a known origin are silently dropped.<br><br>**Costs:** 20 tokens per call that returns at least one item; 5 tokens per call that returns an empty list (empty isn't necessarily an error — the keyword may simply have no live matches).",
"operationId": "publicApiLiveSearch",
"parameters": [
{
"name": "store",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
]
},
"example": "APP_STORE"
},
{
"name": "keyword",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 80
},
"example": "photo editor"
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "device",
"in": "query",
"description": "Device key. App Store: `IPHONE` or `IPAD`. Google Play: `MOBILE`. Fetch the allowed devices via `/v1/common-catalogs/devices`.",
"required": true,
"schema": {
"type": "string",
"enum": [
"IPHONE",
"IPAD",
"MOBILE"
]
},
"example": "IPHONE"
}
],
"responses": {
"200": {
"description": "Top-50 organic results.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiLiveSearchViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/projects/list": {
"get": {
"tags": [
"Projects"
],
"summary": "List user projects",
"description": "Returns every project (app + country) the authenticated user can access: projects they own, projects shared with them, and — for enterprise team leads/owners — projects owned by members below them in the team. Each project carries an `access` block with the project `owner`'s email and the caller's `level` (`read`/`edit`/`owner`). The `id` of each project is what every project-scoped endpoint (tracking, recommended-keywords, competitors) expects as `project_id`.<br><br>**Costs:** 10 tokens per call.",
"operationId": "publicApiGetProjectsList",
"responses": {
"200": {
"description": "List of projects.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/GetProjectsListResultViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/projects/countries-keywords-counts": {
"get": {
"tags": [
"Projects"
],
"summary": "Get per-country keyword counters",
"description": "Returns, for every store country of the project, the tracked / recommended / ranking keyword counters together with their day-over-day `dynamic`. The result is keyed by 2-letter country code.<br><br>**Note:** these counters are pre-aggregated and reflect the **previous day's** snapshot, so they may lag the real data by up to a day. For exact, up-to-the-moment values use the list endpoints directly (e.g. `/v1/tracking/keywords`, `/v1/recommended-keywords`, `/v1/applications/ranking`).<br><br>**Costs:** 20 tokens per call.",
"operationId": "publicApiGetCountriesKeywordsCounts",
"parameters": [
{
"name": "project_id",
"in": "query",
"description": "Sourced from `/v1/projects/list`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"responses": {
"200": {
"description": "Per-country keyword counters.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/CountriesKeywordsCountsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/recommended-keywords": {
"get": {
"tags": [
"Recommended Keywords"
],
"summary": "List recommended keywords",
"description": "Returns the keywords we recommend you track for a project in the given country, surfaced from the project's app metadata, competitors' metadata, store suggestions, current rankings and related keywords. Each entry carries the phrase, the `sources` that proposed it and its current `state` (`recommended` — fresh suggestion, `tracked` — already in your tracking set, `declined` — you previously dismissed it via `/decline`). Filter by state or by source(s) to narrow the working set. The result is paginated — `pagination.total` reflects the filtered universe.<br><br>**Costs:** `max(10, ceil(returned / 100))` tokens — minimum 10 per call, then 1 extra token for every started bucket of 100 keywords returned on the page.",
"operationId": "publicApiListRecommendedKeywords",
"parameters": [
{
"name": "project_id",
"in": "query",
"description": "Sourced from `/v1/projects/list`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "page",
"in": "query",
"description": "Page number (default 1).",
"required": false,
"schema": {
"type": "integer",
"minimum": 1
},
"example": 1
},
{
"name": "per_page",
"in": "query",
"description": "Items per page (min 100, max 1000, default 100).",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 100
},
"example": 100
},
{
"name": "filters[recommended_keyword_state][]",
"in": "query",
"description": "Keep only keywords in the given state(s).",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"recommended",
"tracked",
"declined"
]
},
"maxItems": 50
}
},
{
"name": "filters[sources][]",
"in": "query",
"description": "Keep only keywords from the given sources.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"meta",
"competitors",
"suggestions",
"rankings",
"related"
]
},
"maxItems": 50
}
}
],
"responses": {
"200": {
"description": "Recommended keywords.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiRecommendedKeywordsListViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/recommended-keywords/decline": {
"post": {
"tags": [
"Recommended Keywords"
],
"summary": "Decline recommended keywords",
"description": "Dismisses recommended keywords by their phrase so they stop appearing in the default `/recommended-keywords` listing. Declined keywords remain queryable via `filters[recommended_keyword_state][]=declined`. Reversible — see `/recommended-keywords/undecline`.<br><br>**Costs:** 1 token per call regardless of how many phrases are listed.",
"operationId": "publicApiDeclineRecommendedKeywords",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"country_code",
"keywords"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"example": "photo editor"
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Declined.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/recommended-keywords/undecline": {
"post": {
"tags": [
"Recommended Keywords"
],
"summary": "Undecline recommended keywords",
"description": "Reverses a previous decline — the listed phrases will surface as `recommended` again the next time their sources still propose them.<br><br>**Costs:** 1 token per call regardless of how many phrases are listed.",
"operationId": "publicApiUndeclineRecommendedKeywords",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"country_code",
"keywords"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"example": "photo editor"
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Undeclined.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/store-charts": {
"get": {
"tags": [
"Store Charts"
],
"summary": "Store chart top-500",
"description": "Returns the top-500 chart positions for a (store, country, cluster, category, device) day-by-day across the requested range. Each day's `positions` are sorted ascending by rank; apps not yet indexed on our side are silently skipped. The window cannot exceed **1 week**.<br><br>**Costs:** 10 tokens per day actually returned in `history` — you only pay for data we delivered. Minimum 10 tokens per call, so a misspelled cluster/category that yields no days still costs 10.",
"operationId": "publicApiStoreChartsTop",
"parameters": [
{
"name": "store",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
]
},
"example": "APP_STORE"
},
{
"name": "country",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "cluster_key",
"in": "query",
"description": "Cluster key from `/v1/common-catalogs/clusters`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "top-free"
},
{
"name": "category_key",
"in": "query",
"description": "Category key from `/v1/common-catalogs/categories`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 128
},
"example": "36"
},
{
"name": "device",
"in": "query",
"description": "Device key. App Store: `IPHONE` or `IPAD`. Google Play: `MOBILE`. Sourced from `/v1/common-catalogs/devices`.",
"required": true,
"schema": {
"type": "string",
"enum": [
"IPHONE",
"IPAD",
"MOBILE"
]
},
"example": "IPHONE"
},
{
"name": "date_from",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-05-01"
},
{
"name": "date_to",
"in": "query",
"description": "Must be on or after `date_from` and no more than one week later.",
"required": true,
"schema": {
"type": "string",
"format": "date"
},
"example": "2026-05-07"
}
],
"responses": {
"200": {
"description": "Per-day top-500 history.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiStoreChartsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"422": {
"description": "Validation error."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/subscription/limits": {
"get": {
"tags": [
"Subscription"
],
"summary": "Get subscription limits",
"description": "Returns the plan limits of the authenticated user's current subscription — `max_keywords`, `max_apps`, `max_archived_apps` and `max_public_api_tokens` — each as a `total` (plan allowance) / `used` (currently consumed) pair. Team members see their team owner's plan.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiGetSubscriptionLimits",
"responses": {
"200": {
"description": "Current subscription limits.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/SubscriptionLimitsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/tracking/keywords": {
"get": {
"tags": [
"Tracking Keywords"
],
"summary": "List tracked keywords",
"description": "Returns every keyword you currently track on a project for the given country, with each keyword's detected language and the folders it belongs to. A cross-country folder (`settings.cross_country = true`, see `GET /v1/tracking/folders`) is reported for the keyword in every country it is tracked in, no matter which country it was added to the folder from; a country-scoped folder only in its own country.<br><br>Dropping a keyword from tracking in one country only takes it out of country-scoped folders of that country — in the remaining countries it stays in its folders.<br><br>Use the endpoint to enumerate the tracking set you're billing against, and to feed the `keyword_ids` parameter of the delete endpoint.<br><br>**Costs:** 1 token per 100 returned keywords, minimum 1 per call.",
"operationId": "publicApiListTrackedKeywords",
"parameters": [
{
"name": "project_id",
"in": "query",
"description": "Sourced from `/v1/projects/list`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
},
{
"name": "country_code",
"in": "query",
"description": "Sourced from `/v1/common-catalogs/countries`.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"example": "US"
},
{
"name": "filters[folder_ids][]",
"in": "query",
"description": "Keep only keywords that belong to at least one of the given folders (ids sourced from `GET /v1/tracking/folders`).",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "integer",
"example": 123
},
"maxItems": 100
}
},
{
"name": "filters[deduplicate_modificators]",
"in": "query",
"description": "Collapse phrases that differ only by leading/trailing punctuation or letter case (modificators of the same normalized phrase) into a single row, preferring the plain phrase. Off by default — every tracked phrase is returned as is.",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"example": true
}
],
"responses": {
"200": {
"description": "Tracked keywords.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiTrackingKeywordsListViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
},
"post": {
"tags": [
"Tracking Keywords"
],
"summary": "Add tracked keywords",
"description": "Starts tracking the given keywords on a project for the given country. Keywords already tracked are silently de-duplicated and not billed. Returns 403 if the request would push the project past the plan's tracked-keyword limit — nothing is added in that case.<br><br>**Costs:** 5 tokens per *new* keyword actually added. A request consisting entirely of already-tracked keywords is free.",
"operationId": "publicApiAddTrackedKeywords",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"country_code",
"keywords"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"example": "photo editor"
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Stored keywords.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiAddedKeywordsViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "Plan keyword limit exceeded, or no access to the project.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicApiKeywordsLimitExceededSchema"
},
{
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
]
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
},
"delete": {
"tags": [
"Tracking Keywords"
],
"summary": "Delete tracked keywords",
"description": "Stops tracking the given keywords by their numeric `keyword_ids` (from `GET /v1/tracking/keywords`). Removed keywords stop counting against the plan's tracked-keyword limit and we stop collecting their positions going forward — historical positions remain queryable via `/v1/keywords/ranking` for as long as the date range covers them.<br><br>**Costs:** 1 token per call regardless of how many keywords were removed.",
"operationId": "publicApiDeleteTrackedKeywords",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"country_code",
"keyword_ids"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keyword_ids": {
"description": "Sourced from `GET /v1/tracking/keywords`.",
"type": "array",
"items": {
"type": "integer",
"example": 456
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Deleted.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/tracking/folders": {
"get": {
"tags": [
"Tracking Folders"
],
"summary": "List folders",
"description": "Returns the keyword folders defined on a project — the groupings you can use to organise tracked keywords (e.g. by theme, campaign or language).<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiListFolders",
"parameters": [
{
"name": "project_id",
"in": "query",
"description": "Sourced from `/v1/projects/list`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"responses": {
"200": {
"description": "Folders.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiFoldersListViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
},
"post": {
"tags": [
"Tracking Folders"
],
"summary": "Create folder",
"description": "Creates a new empty folder on a project. The returned folder id feeds the folder-keywords endpoints to populate it.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiCreateFolder",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"name"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"maxLength": 255,
"example": "My folder"
},
"description": {
"type": "string",
"maxLength": 1000,
"example": "Optional description",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Created folder.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiFolderViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/tracking/folders/{folder}": {
"delete": {
"tags": [
"Tracking Folders"
],
"summary": "Delete folder",
"description": "Deletes a folder. The keywords inside the folder remain tracked on the project — only the folder grouping is removed. Returns 404 if the folder doesn't belong to any project of the authenticated user.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiDeleteFolder",
"parameters": [
{
"name": "folder",
"in": "path",
"description": "Sourced from `GET /v1/tracking/folders`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"responses": {
"200": {
"description": "Deleted.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"404": {
"description": "Folder not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiFolderNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
},
"patch": {
"tags": [
"Tracking Folders"
],
"summary": "Update folder",
"description": "Renames a folder, updates its description and/or its cross-country setting. Omit a field to leave it unchanged. With `settings.cross_country = true` the folder spans every country of the project — a keyword added to it in one country is reported as belonging to the folder in all of them; with `false` the folder membership is country-scoped. New folders are cross-country by default. Returns 404 if the folder doesn't belong to any project of the authenticated user.<br><br>**Costs:** 1 token per call.",
"operationId": "publicApiUpdateFolder",
"parameters": [
{
"name": "folder",
"in": "path",
"description": "Sourced from `GET /v1/tracking/folders`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"example": "Renamed folder"
},
"description": {
"type": "string",
"maxLength": 1000,
"example": "New description",
"nullable": true
},
"settings": {
"required": [
"cross_country"
],
"properties": {
"cross_country": {
"description": "`true` — the folder spans every country of the project, `false` — its keywords are country-scoped.",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Updated folder.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiFolderViewSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"404": {
"description": "Folder not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiFolderNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
},
"/public-api/v1/tracking/folders/{folder}/keywords": {
"post": {
"tags": [
"Tracking Folders"
],
"summary": "Add keywords to folder",
"description": "Adds the given keywords (by phrase) to a folder on a project for the given country. Idempotent — keywords already in the folder are a no-op. Returns 404 if the project or folder doesn't belong to the authenticated user.<br><br>**Costs:** 1 token per 100 keywords in the request, minimum 1 per call.",
"operationId": "publicApiAddKeywordsToFolder",
"parameters": [
{
"name": "folder",
"in": "path",
"description": "Sourced from `GET /v1/tracking/folders`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"country_code",
"keywords"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Sourced from `/v1/common-catalogs/countries`.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"example": "photo editor"
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Added.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project or folder not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiFolderNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
},
"delete": {
"tags": [
"Tracking Folders"
],
"summary": "Remove keywords from folder",
"description": "Removes the given keywords (by phrase) from a folder. The keywords stay tracked on the project — only the folder membership is removed. Returns 404 if the project or folder doesn't belong to the authenticated user.<br><br>**`country_code` is optional.** Omit it and the keyword leaves the folder entirely — in every country, exactly as it behaves for a cross-country folder (`settings.cross_country = true`). Pass it and a country-scoped folder (`settings.cross_country = false`) loses the membership of that country only, keeping the keyword in the folder in its other countries. For a cross-country folder the parameter changes nothing: such a folder holds a single membership shared by all countries, so removing it always removes it everywhere.<br><br>**Costs:** 1 token per 100 keywords in the request, minimum 1 per call.",
"operationId": "publicApiRemoveKeywordsFromFolder",
"parameters": [
{
"name": "folder",
"in": "path",
"description": "Sourced from `GET /v1/tracking/folders`.",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"project_id",
"keywords"
],
"properties": {
"project_id": {
"description": "Sourced from `/v1/projects/list`.",
"type": "integer",
"example": 123
},
"country_code": {
"description": "Optional. Sourced from `/v1/common-catalogs/countries`. Omit it to remove the keyword from the folder in every country; pass it to remove only this country's membership of a country-scoped folder. Ignored for cross-country folders.",
"type": "string",
"maxLength": 2,
"minLength": 2,
"example": "US"
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"example": "photo editor"
},
"maxItems": 1000,
"minItems": 1
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Removed.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiSuccessSchema"
}
},
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Missing or invalid public API token."
},
"403": {
"description": "No access to the project.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiProjectAccessDeniedSchema"
}
}
}
},
"404": {
"description": "Project or folder not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiFolderNotFoundSchema"
}
}
}
},
"402": {
"description": "Not enough tokens on the balance.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiNotEnoughTokensSchema"
}
},
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal error.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/PublicApiResponseViewSchema"
},
{
"properties": {
"data": {
"$ref": "#/components/schemas/PublicApiInternalErrorSchema"
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"publicApiToken": []
}
]
}
}
},
"components": {
"schemas": {
"GetProjectsListResultViewSchema": {
"properties": {
"projects": {
"type": "array",
"items": {
"allOf": [
{
"properties": {
"id": {
"type": "integer",
"example": 123
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/StoreViewSchema"
},
{
"$ref": "#/components/schemas/AppCommonInfoViewSchema"
},
{
"$ref": "#/components/schemas/ProjectAccessViewSchema"
}
]
}
}
},
"type": "object"
},
"ApiTokensBalanceViewSchema": {
"properties": {
"tokens_balance": {
"properties": {
"amount": {
"type": "integer",
"example": 4990
},
"used": {
"type": "integer",
"example": 10
},
"renewed_at": {
"type": "string",
"example": "2026-05-01 00:00:00"
},
"last_balance_transactions": {
"description": "Up to 100 most recent transactions on this balance, newest first. No `cause_details` — fetch them out-of-band if needed.",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "01906db5-9f02-7c2c-9c33-7af80d8baf12"
},
"cause": {
"description": "Endpoint key that triggered the debit (e.g. `live-search`); null for system-issued rows like balance renewal.",
"type": "string",
"example": "live-search",
"nullable": true
},
"amount": {
"description": "Signed delta on the balance (debits are negative).",
"type": "integer",
"example": -20
},
"datetime": {
"type": "string",
"format": "date-time",
"example": "2026-05-25T14:00:00+03:00"
},
"request": {
"description": "Originating public-API request (null for system-issued rows).",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "9b9c5a3e-1f0e-4d3a-9f15-1b1bd8c1e9c4"
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
},
"type": "object"
},
"CommonItemInfoViewSchema": {
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"title": {
"type": "string",
"example": "My App"
}
},
"type": "object"
},
"AppCommonInfoViewSchema": {
"properties": {
"app_info": {
"$ref": "#/components/schemas/CommonItemInfoViewSchema"
}
},
"type": "object"
},
"PublicApiAppNotFoundSchema": {
"properties": {
"error": {
"type": "string",
"example": "Application not found"
}
},
"type": "object"
},
"PublicApiApplicationAvailabilityViewSchema": {
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"available_countries": {
"description": "Country codes where the app is available.",
"type": "array",
"items": {
"type": "string",
"example": "US"
}
}
},
"type": "object"
},
"PublicApiAppInstallsHistoryViewSchema": {
"properties": {
"countries": {
"description": "One entry per country from our catalog. `history` is chronological and carries one point per requested month; missing data appears as `installs: null`.",
"type": "array",
"items": {
"properties": {
"code": {
"type": "string",
"example": "US"
},
"history": {
"type": "array",
"items": {
"properties": {
"period": {
"type": "string",
"example": "2026-03"
},
"installs": {
"type": "integer",
"example": 12345,
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"PublicApiApplicationMediaViewSchema": {
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"media": {
"description": "Latest media keyed by requested locale. Only locales that carry media are present.",
"type": "object",
"example": {
"en_US": {
"screenshots": [
{
"url": "https://…/screenshot.png",
"device": "iphone6",
"position": 1
}
],
"videos": [
{
"url": "https://…/video.mp4",
"device": "iphone6"
}
],
"logo": {
"url": "https://…/logo.png"
}
}
},
"additionalProperties": {
"$ref": "#/components/schemas/PublicApiApplicationMediaLocaleSchema"
}
}
},
"type": "object"
},
"AppMediaView": {
"$ref": "#/components/schemas/PublicApiApplicationMediaLocaleSchema"
},
"PublicApiApplicationMediaLocaleSchema": {
"properties": {
"screenshots": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiScreenshotViewSchema"
}
},
"videos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiVideoViewSchema"
}
},
"logo": {
"oneOf": [
{
"$ref": "#/components/schemas/PublicApiLogoViewSchema"
}
],
"nullable": true
}
},
"type": "object"
},
"PublicApiApplicationMetadataViewSchema": {
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"metadata": {
"description": "Latest text metadata keyed by requested locale. Only locales that carry data are present.",
"type": "object",
"example": {
"en_US": {
"title": "My App",
"sub_title": "Best app ever",
"description": "Full description…"
}
},
"additionalProperties": {
"$ref": "#/components/schemas/PublicApiApplicationMetadataLocaleSchema"
}
}
},
"type": "object"
},
"AppMetadataView": {
"$ref": "#/components/schemas/PublicApiApplicationMetadataLocaleSchema"
},
"PublicApiApplicationMetadataLocaleSchema": {
"properties": {
"title": {
"type": "string",
"example": "My App"
},
"sub_title": {
"type": "string",
"example": "Best app ever"
},
"description": {
"type": "string",
"example": "Full description…",
"nullable": true
}
},
"type": "object"
},
"PublicApiAppRankingRowViewSchema": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2025-12-15"
},
"keyword": {
"type": "string",
"example": "photo editor"
},
"position": {
"type": "integer",
"example": 12
}
},
"type": "object"
},
"PublicApiAppRevenueHistoryViewSchema": {
"properties": {
"countries": {
"description": "One entry per country from our catalog. `history` is chronological and carries one point per requested month; missing data appears as `revenue: null`.",
"type": "array",
"items": {
"properties": {
"code": {
"type": "string",
"example": "US"
},
"history": {
"type": "array",
"items": {
"properties": {
"period": {
"type": "string",
"example": "2026-03"
},
"revenue": {
"type": "integer",
"example": 4500,
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"PublicApiApplicationVersionsViewSchema": {
"properties": {
"versions": {
"description": "Version history, newest first. Empty when the app has no aggregated version data.",
"type": "array",
"items": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2026-04-12"
},
"version": {
"type": "string",
"example": "3.14.0"
},
"description": {
"type": "string",
"example": "Bug fixes and performance improvements."
}
},
"type": "object"
}
}
},
"type": "object"
},
"PublicApiApplicationsAvailabilityViewSchema": {
"properties": {
"applications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiApplicationAvailabilityViewSchema"
}
}
},
"type": "object"
},
"PublicApiApplicationsMediaViewSchema": {
"properties": {
"applications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiApplicationMediaViewSchema"
}
}
},
"type": "object"
},
"PublicApiApplicationsMetadataViewSchema": {
"properties": {
"applications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiApplicationMetadataViewSchema"
}
}
},
"type": "object"
},
"ApplicationsRankingLatestByKeywordsViewSchema": {
"description": "Map keyed by keyword. Each entry holds the app's latest known position for that keyword and the date that position was parsed. Dates may differ between keywords. Keywords the app does not currently rank for are omitted.",
"type": "object",
"example": {
"fitness app": {
"date": "2025-12-15",
"position": 1
},
"workout tracker": {
"date": "2025-12-14",
"position": 7
}
},
"additionalProperties": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2025-12-15"
},
"position": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
},
"PublicApiApplicationsRankingViewSchema": {
"properties": {
"pagination": {
"$ref": "#/components/schemas/PublicApiPaginationViewSchema"
},
"ranking": {
"description": "Flat list of `(date, keyword, position)` rows for the current page.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiAppRankingRowViewSchema"
}
}
},
"type": "object"
},
"PublicApiLogoViewSchema": {
"properties": {
"url": {
"type": "string",
"example": "https://…/logo.png"
}
},
"type": "object"
},
"PublicApiScreenshotViewSchema": {
"properties": {
"url": {
"type": "string",
"example": "https://…/screenshot.png"
},
"device": {
"type": "string",
"example": "iphone6",
"nullable": true
},
"position": {
"type": "integer",
"example": 1,
"nullable": true
}
},
"type": "object"
},
"PublicApiVideoViewSchema": {
"properties": {
"url": {
"type": "string",
"example": "https://…/video.mp4"
},
"device": {
"type": "string",
"example": "iphone6",
"nullable": true
}
},
"type": "object"
},
"PublicApiBalanceNotFoundSchema": {
"properties": {
"error": {
"type": "string",
"example": "Balance not found"
}
},
"type": "object"
},
"CommonCatalogsCategoriesViewSchema": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "6005"
},
"name": {
"type": "string",
"example": "Social Networking"
}
},
"type": "object"
}
},
"CommonCatalogsClustersViewSchema": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "topfreeapplications"
},
"name": {
"type": "string",
"example": "Top Free"
}
},
"type": "object"
}
},
"CommonCatalogsCountriesViewSchema": {
"type": "array",
"items": {
"properties": {
"code": {
"type": "string",
"example": "US"
},
"name": {
"type": "string",
"example": "United States"
}
},
"type": "object"
}
},
"CommonCatalogsDevicesViewSchema": {
"type": "array",
"items": {
"properties": {
"key": {
"type": "string",
"example": "IPHONE"
}
},
"type": "object"
}
},
"CommonCatalogsLocalesViewSchema": {
"type": "array",
"items": {
"properties": {
"code": {
"type": "string",
"example": "en_US"
},
"name": {
"type": "string",
"example": "English (United States)"
}
},
"type": "object"
}
},
"CommonCategoryInfoViewSchema": {
"properties": {
"name": {
"description": "Standardized category shape reused across public-API endpoints.",
"type": "string",
"example": "Games"
}
},
"type": "object"
},
"CommonDeveloperInfoViewSchema": {
"properties": {
"name": {
"description": "Standardized developer shape reused across public-API endpoints.",
"type": "string",
"example": "Acme Studios"
}
},
"type": "object"
},
"PublicApiCompetitorViewSchema": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/AppCommonInfoViewSchema"
},
{
"properties": {
"state": {
"type": "string",
"enum": [
"competitor",
"non_competitor",
"indirect_competitor"
],
"example": "competitor"
}
},
"type": "object"
}
]
},
"PublicApiCompetitorsListViewSchema": {
"properties": {
"competitors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiCompetitorViewSchema"
}
}
},
"type": "object"
},
"CountriesKeywordsCountsViewSchema": {
"description": "Map keyed by 2-letter country code. Each country carries the tracked / recommended / ranking keyword counters and their day-over-day dynamic.",
"type": "object",
"example": {
"US": {
"tracking": {
"count": 120,
"dynamic": 4
},
"recommended": {
"count": 35,
"dynamic": -2
},
"ranking": {
"count": 5023,
"dynamic": 17
}
}
},
"additionalProperties": {
"properties": {
"tracking": {
"properties": {
"count": {
"type": "integer",
"example": 120
},
"dynamic": {
"description": "Change versus the previous day.",
"type": "integer",
"example": 4
}
},
"type": "object"
},
"recommended": {
"properties": {
"count": {
"type": "integer",
"example": 35
},
"dynamic": {
"description": "Change versus the previous day.",
"type": "integer",
"example": -2
}
},
"type": "object"
},
"ranking": {
"properties": {
"count": {
"type": "integer",
"example": 5023
},
"dynamic": {
"description": "Change versus the previous day.",
"type": "integer",
"example": 17
}
},
"type": "object"
}
},
"type": "object"
}
},
"PublicApiFolderNotFoundSchema": {
"properties": {
"error": {
"type": "string",
"example": "Folder not found"
}
},
"type": "object"
},
"PublicApiInternalErrorSchema": {
"properties": {
"error": {
"type": "string",
"example": "Internal Server Error"
}
},
"type": "object"
},
"PublicApiForceRecheckRankingViewSchema": {
"properties": {
"status": {
"description": "The re-check has been queued. Completion is reported per keyword through the webhook, if one was supplied.",
"type": "string",
"enum": [
"accepted"
],
"example": "accepted"
}
},
"type": "object"
},
"PublicApiKeywordPopularityHistoryDateViewSchema": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2025-08-12"
},
"popularity": {
"description": "Raw popularity (App Store only).",
"type": "integer",
"example": 50,
"nullable": true
},
"mlp_popularity": {
"description": "ML-derived popularity. The only popularity field returned for Google Play.",
"type": "integer",
"example": 45,
"nullable": true
}
},
"type": "object"
},
"PublicApiKeywordPopularityViewSchema": {
"properties": {
"keyword": {
"type": "string",
"example": "photo editor"
},
"history": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordPopularityHistoryDateViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordRankingDateViewSchema": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2025-08-12"
},
"positions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordRankingPositionViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordRankingPositionViewSchema": {
"properties": {
"position": {
"type": "integer",
"example": 1
},
"item": {
"$ref": "#/components/schemas/CommonItemInfoViewSchema"
}
},
"type": "object"
},
"PublicApiKeywordRankingViewSchema": {
"properties": {
"keyword": {
"type": "string",
"example": "photo editor"
},
"history": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordRankingDateViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordsMetricsViewSchema": {
"properties": {
"metrics": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordMetricsItemViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordMetricsItemViewSchema": {
"properties": {
"keyword": {
"type": "string",
"example": "photo editor"
},
"popularity": {
"description": "App Store only. Raw scan popularity. Absent when not requested or no scan available.",
"type": "integer",
"example": 42,
"nullable": true
},
"mlp_popularity": {
"description": "ML-derived popularity. App Store and Google Play.",
"type": "integer",
"example": 45,
"nullable": true
},
"max_popularity": {
"description": "App Store only. Year-max raw popularity.",
"type": "integer",
"example": 78,
"nullable": true
},
"mlp_max_popularity": {
"description": "Year-max ML-derived popularity.",
"type": "integer",
"example": 80,
"nullable": true
},
"impressions": {
"description": "App Store only. Estimated daily impressions for real popularity.",
"type": "integer",
"example": 15000,
"nullable": true
},
"mlp_impressions": {
"description": "Estimated daily impressions for ML-derived popularity.",
"type": "integer",
"example": 16000,
"nullable": true
},
"difficulty": {
"description": "Keyword difficulty score (0–10). Single value, no real/mlp split.",
"type": "integer",
"example": 7,
"nullable": true
},
"language": {
"description": "Detected language. Country-independent. Absent when not requested.",
"properties": {
"code": {
"type": "string",
"example": "en"
},
"name": {
"type": "string",
"example": "English"
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
},
"PublicApiKeywordsPopularityViewSchema": {
"properties": {
"popularity": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordPopularityViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordsRankingViewSchema": {
"properties": {
"ranking": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiKeywordRankingViewSchema"
}
}
},
"type": "object"
},
"PublicApiKeywordsLimitExceededSchema": {
"properties": {
"error": {
"type": "string",
"example": "Plan keyword limit exceeded"
}
},
"type": "object"
},
"LiveSearchAppLiveDataViewSchema": {
"description": "Live application data as it appears in the store at request time (not the cached DB copy).",
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"title": {
"type": "string",
"example": "My App"
},
"subtitle": {
"type": "string",
"example": "Best app ever"
},
"logo": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../logo.png"
},
"url": {
"type": "string",
"example": "https://apps.apple.com/app/id1234567890"
},
"developer": {
"$ref": "#/components/schemas/CommonDeveloperInfoViewSchema"
},
"main_category": {
"$ref": "#/components/schemas/CommonCategoryInfoViewSchema"
},
"rating": {
"type": "number",
"format": "float",
"example": 4.5
},
"votes_count": {
"type": "integer",
"example": 12345
},
"screenshots": {
"type": "array",
"items": {
"properties": {
"url": {
"type": "string"
},
"position": {
"type": "integer"
}
},
"type": "object"
},
"example": [
{
"url": "https://is1-ssl.mzstatic.com/image/.../screenshot.png",
"position": 1
}
]
}
},
"type": "object"
},
"LiveSearchBundleLiveDataViewSchema": {
"description": "Live app-bundle data as it appears in the store at request time.",
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"title": {
"type": "string",
"example": "My Bundle"
},
"logo": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../logo.png"
},
"url": {
"type": "string",
"example": "https://apps.apple.com/app-bundle/id1234567890"
},
"main_category": {
"type": "string",
"example": "Games"
},
"apps": {
"type": "array",
"items": {
"properties": {
"origin_id": {
"type": "string"
},
"title": {
"type": "string"
},
"logo": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"example": [
{
"origin_id": "987654321",
"title": "Bundled App",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id987654321"
}
]
}
},
"type": "object"
},
"LiveSearchDeveloperLiveDataViewSchema": {
"description": "Live developer-page data as it appears in the store at request time.",
"properties": {
"origin_id": {
"type": "string",
"example": "284882215"
},
"title": {
"type": "string",
"example": "Acme Studios"
},
"logo": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../logo.png"
},
"url": {
"type": "string",
"example": "https://apps.apple.com/developer/id284882215"
},
"apps": {
"type": "array",
"items": {
"properties": {
"origin_id": {
"type": "string"
},
"title": {
"type": "string"
},
"logo": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"example": [
{
"origin_id": "987654321",
"title": "Developer App",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id987654321"
}
]
}
},
"type": "object"
},
"LiveSearchEditorialLiveDataViewSchema": {
"description": "Live editorial-item data as it appears in the store at request time.",
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"title": {
"type": "string",
"example": "Editor's Pick"
},
"logo": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../logo.png"
},
"url": {
"type": "string",
"example": "https://apps.apple.com/story/id1234567890"
}
},
"type": "object"
},
"LiveSearchIapLiveDataViewSchema": {
"description": "Live in-app-purchase / subscription data as it appears in the store at request time.",
"properties": {
"origin_id": {
"type": "string",
"example": "1234567890"
},
"title": {
"type": "string",
"example": "Premium subscription"
},
"logo": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../logo.png"
},
"url": {
"type": "string",
"example": "https://apps.apple.com/app/id1234567890"
},
"image": {
"type": "string",
"example": "https://is1-ssl.mzstatic.com/image/.../banner.png"
},
"price": {
"type": "number",
"format": "float",
"example": 9.99
}
},
"type": "object"
},
"LiveSearchItemViewSchema": {
"properties": {
"type": {
"description": "Item type: `apps`, `preorder`, `app-bundles`, `developers`, `editorial-items`, `in-apps`, `subscription`.",
"type": "string",
"example": "apps"
},
"is_paid": {
"description": "True when the slot is a paid ad placement.",
"type": "boolean",
"example": false
},
"position": {
"description": "1-based rank in the result list (paid placements included).",
"type": "integer",
"example": 1
},
"live_data": {
"description": "Live store data captured at request time (logo, title, screenshots, …) — reflects the store right now, not the possibly-stale DB copy. Shape varies per `type`, but always carries `origin_id` and `title`.",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/LiveSearchAppLiveDataViewSchema"
},
{
"$ref": "#/components/schemas/LiveSearchBundleLiveDataViewSchema"
},
{
"$ref": "#/components/schemas/LiveSearchDeveloperLiveDataViewSchema"
},
{
"$ref": "#/components/schemas/LiveSearchEditorialLiveDataViewSchema"
},
{
"$ref": "#/components/schemas/LiveSearchIapLiveDataViewSchema"
}
]
}
},
"type": "object"
},
"PublicApiLiveSearchViewSchema": {
"properties": {
"items": {
"description": "One entry per result slot. `live_data` is a `oneOf` — its shape depends on `type`. The example below shows one item of every possible type.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LiveSearchItemViewSchema"
},
"example": [
{
"type": "apps",
"is_paid": false,
"position": 1,
"live_data": {
"origin_id": "1234567890",
"title": "My App",
"subtitle": "Best app ever",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id1234567890",
"developer": {
"name": "Acme Studios"
},
"main_category": {
"name": "Games"
},
"rating": 4.5,
"votes_count": 12345,
"screenshots": [
{
"url": "https://is1-ssl.mzstatic.com/image/.../screenshot.png",
"position": 1
}
]
}
},
{
"type": "preorder",
"is_paid": false,
"position": 2,
"live_data": {
"origin_id": "1234567891",
"title": "Upcoming App",
"subtitle": "Coming soon",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id1234567891",
"developer": {
"name": "Acme Studios"
},
"main_category": {
"name": "Games"
},
"rating": 0,
"votes_count": 0,
"screenshots": [
{
"url": "https://is1-ssl.mzstatic.com/image/.../screenshot.png",
"position": 1
}
]
}
},
{
"type": "app-bundles",
"is_paid": false,
"position": 3,
"live_data": {
"origin_id": "1234500001",
"title": "My Bundle",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app-bundle/id1234500001",
"main_category": {
"name": "Games"
},
"apps": [
{
"origin_id": "987654321",
"title": "Bundled App",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id987654321"
}
]
}
},
{
"type": "developers",
"is_paid": false,
"position": 4,
"live_data": {
"origin_id": "284882215",
"title": "Acme Studios",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/developer/id284882215",
"apps": [
{
"origin_id": "987654321",
"title": "Developer App",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id987654321"
}
]
}
},
{
"type": "editorial-items",
"is_paid": false,
"position": 5,
"live_data": {
"origin_id": "1234500002",
"title": "Editor's Pick",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/story/id1234500002"
}
},
{
"type": "in-apps",
"is_paid": false,
"position": 6,
"live_data": {
"origin_id": "1234500003",
"title": "Coins pack",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id1234567890",
"image": "https://is1-ssl.mzstatic.com/image/.../banner.png",
"price": 4.99
}
},
{
"type": "subscription",
"is_paid": false,
"position": 7,
"live_data": {
"origin_id": "1234500004",
"title": "Premium subscription",
"logo": "https://is1-ssl.mzstatic.com/image/.../logo.png",
"url": "https://apps.apple.com/app/id1234567890",
"image": "https://is1-ssl.mzstatic.com/image/.../banner.png",
"price": 9.99
}
}
]
}
},
"type": "object"
},
"PublicApiNotEnoughTokensSchema": {
"properties": {
"error": {
"type": "string",
"example": "Not enough tokens"
},
"tokens_balance": {
"properties": {
"amount": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
},
"type": "object"
},
"PublicApiPaginationViewSchema": {
"properties": {
"current_page": {
"description": "Canonical `pagination` meta block returned by every paginating public-API endpoint. Compose\ninto your endpoint view via `array_merge` / spread so the wire shape stays identical across\nendpoints. Pair with `App\\PublicApi\\Object\\PaginatedCollection`.",
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 30
},
"total": {
"description": "Total items in the full result, before slicing.",
"type": "integer",
"example": 120
},
"total_pages": {
"type": "integer",
"example": 4
}
},
"type": "object"
},
"PublicApiProjectAccessDeniedSchema": {
"properties": {
"error": {
"type": "string",
"example": "Access to the project is denied"
}
},
"type": "object"
},
"ProjectAccessViewSchema": {
"properties": {
"access": {
"properties": {
"owner": {
"properties": {
"email": {
"description": "Describes the authenticated API user's access to a project (user_application):\nwho owns it and at what level the caller may use it.",
"type": "string",
"example": "owner@example.com"
}
},
"type": "object"
},
"level": {
"type": "string",
"enum": [
"read",
"edit",
"owner"
],
"example": "owner"
}
},
"type": "object"
}
},
"type": "object"
},
"PublicApiProjectNotFoundSchema": {
"properties": {
"error": {
"type": "string",
"example": "Project not found"
}
},
"type": "object"
},
"PublicApiResponseViewSchema": {
"properties": {
"request": {
"properties": {
"id": {
"description": "Standard public API response envelope. The `data` payload varies per endpoint –\ncompose it with `allOf` against the relevant data schema when documenting a response.",
"type": "string",
"example": "req-uuid"
}
},
"type": "object"
},
"data": {
"description": "Endpoint-specific payload — see the per-operation `data` schema.",
"type": "object"
}
},
"type": "object"
},
"PublicApiRateLimitExceededSchema": {
"properties": {
"error": {
"type": "string",
"example": "Too many requests"
}
},
"type": "object"
},
"PublicApiRecommendedKeywordViewSchema": {
"properties": {
"keyword": {
"properties": {
"value": {
"type": "string",
"example": "photo editor"
}
},
"type": "object"
},
"state": {
"type": "string",
"enum": [
"recommended",
"tracked",
"declined"
],
"example": "recommended"
},
"sources": {
"type": "array",
"items": {
"type": "string",
"example": "suggestions"
}
}
},
"type": "object"
},
"PublicApiRecommendedKeywordsListViewSchema": {
"properties": {
"pagination": {
"$ref": "#/components/schemas/PublicApiPaginationViewSchema"
},
"keywords": {
"description": "Recommended keywords for the current page.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiRecommendedKeywordViewSchema"
}
}
},
"type": "object"
},
"PublicApiStoreChartsViewSchema": {
"properties": {
"history": {
"description": "One entry per day in the requested range, chronological. Each day carries up to 500 ranked positions.",
"type": "array",
"items": {
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2026-05-01"
},
"positions": {
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"properties": {
"position": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/AppCommonInfoViewSchema"
}
]
}
}
},
"type": "object"
}
}
},
"type": "object"
},
"StoreViewSchema": {
"properties": {
"store": {
"properties": {
"key": {
"type": "string",
"enum": [
"APP_STORE",
"GOOGLE_PLAY"
],
"example": "APP_STORE"
}
},
"type": "object"
}
},
"type": "object"
},
"SubscriptionLimitsViewSchema": {
"description": "Plan limits of the authenticated user's current subscription. Each entry carries the plan allowance (`total`) and how much of it is already consumed (`used`).",
"properties": {
"limits": {
"properties": {
"max_keywords": {
"properties": {
"total": {
"type": "integer",
"example": 1000
},
"used": {
"type": "integer",
"example": 120
}
},
"type": "object"
},
"max_apps": {
"properties": {
"total": {
"type": "integer",
"example": 10
},
"used": {
"type": "integer",
"example": 3
}
},
"type": "object"
},
"max_archived_apps": {
"properties": {
"total": {
"type": "integer",
"example": 5
},
"used": {
"type": "integer",
"example": 1
}
},
"type": "object"
},
"max_public_api_tokens": {
"properties": {
"total": {
"type": "integer",
"example": 50000
},
"used": {
"type": "integer",
"example": 4200
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"PublicApiSuccessSchema": {
"properties": {
"success": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"PublicApiAddedKeywordsViewSchema": {
"properties": {
"new_count": {
"description": "Number of keywords that were not tracked before (the billable amount).",
"type": "integer",
"example": 3
},
"keywords": {
"description": "The newly tracked phrases.",
"type": "array",
"items": {
"type": "string",
"example": "photo editor"
}
}
},
"type": "object"
},
"PublicApiFolderViewSchema": {
"properties": {
"id": {
"type": "integer",
"example": 123
},
"name": {
"type": "string",
"example": "My folder"
},
"settings": {
"properties": {
"cross_country": {
"description": "`true` — the folder spans every country of the project, `false` — its keywords are country-scoped.",
"type": "boolean",
"example": true
}
},
"type": "object"
}
},
"type": "object"
},
"PublicApiFoldersListViewSchema": {
"properties": {
"folders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiFolderViewSchema"
}
}
},
"type": "object"
},
"PublicApiTrackingKeywordViewSchema": {
"properties": {
"id": {
"type": "integer",
"example": 456
},
"keyword": {
"type": "string",
"example": "photo editor"
},
"language": {
"properties": {
"name": {
"type": "string",
"example": "English"
},
"code": {
"type": "string",
"example": "en"
}
},
"type": "object",
"nullable": true
},
"folders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiFolderViewSchema"
}
}
},
"type": "object"
},
"PublicApiTrackingKeywordsListViewSchema": {
"properties": {
"keywords": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PublicApiTrackingKeywordViewSchema"
}
}
},
"type": "object"
}
},
"securitySchemes": {
"publicApiToken": {
"type": "apiKey",
"description": "Personal public API token issued to the user.",
"name": "X-PUBLIC-API-TOKEN",
"in": "header"
}
}
},
"tags": [
{
"name": "Applications",
"description": "Applications"
},
{
"name": "Balance",
"description": "Balance"
},
{
"name": "Common Catalogs",
"description": "Common Catalogs"
},
{
"name": "Competitors",
"description": "Competitors"
},
{
"name": "Keywords",
"description": "Keywords"
},
{
"name": "Live Search",
"description": "Live Search"
},
{
"name": "Projects",
"description": "Projects"
},
{
"name": "Recommended Keywords",
"description": "Recommended Keywords"
},
{
"name": "Store Charts",
"description": "Store Charts"
},
{
"name": "Subscription",
"description": "Subscription"
},
{
"name": "Tracking Keywords",
"description": "Tracking Keywords"
},
{
"name": "Tracking Folders",
"description": "Tracking Folders"
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |