{ "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.

**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" }, "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" }, "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.

**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" }, "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" }, "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.

**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" }, "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).

**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" }, "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.

**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" }, "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.

**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" }, "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).

**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" }, "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", "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", "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/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.

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

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

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

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

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

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

**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" ] } } } ], "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." }, "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.

**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", "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." }, "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.

**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", "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." }, "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/track": { "post": { "tags": [ "Keywords" ], "summary": "Track keyword rankings", "description": "Runs an on-demand keyword-ranking scan for a (store, country) and returns each keyword's top positions with the apps holding them. Use this when you need fresh ranking data *now* for keywords you don't already have tracked. Without `response_conf` the call blocks on the scan and the response carries the result; with `response_conf.url` the task is queued and the result is later POSTed to that URL (the immediate response then only carries task info). Up to 500 keywords per request. Keywords already in your tracked-keyword quota are billed as free; the remainder are **paid keywords**.

**Costs:** 5 tokens per paid keyword, minimum 5 per call.", "operationId": "publicApiTrackKeywordsRanking", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "store", "country_code", "keywords" ], "properties": { "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" }, "keywords": { "type": "array", "items": { "type": "string", "example": "photo editor" }, "maxItems": 500, "minItems": 1 }, "custom_data": { "description": "Arbitrary key/value data echoed back in the task info.", "type": "object", "example": { "client_request_id": "abc-123", "campaign": "spring-2026" }, "nullable": true, "additionalProperties": true }, "response_conf": { "description": "When present, the task is processed asynchronously and the result is POSTed to `url`.", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "headers": { "description": "Additional headers sent with the callback request. Values are strings.", "type": "object", "example": { "Authorization": "Bearer xxx", "X-Trace-Id": "abc" }, "nullable": true, "additionalProperties": true } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Synchronous result, or task info when processed asynchronously.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiResponseViewSchema" }, { "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/TrackKeywordsRankingResultViewSchema" }, { "$ref": "#/components/schemas/TrackKeywordsRankingTaskInfoViewSchema" } ] } }, "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/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).

**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).", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "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).

**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).", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "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.

**Metric availability by store:**
- `popularity` — App Store only (raw scan); Google Play omits the `popularity` field, only `mlp_popularity` is returned.
- `max_popularity` — App Store: `year_max_popularity` (raw) and `synthetic_year_max_popularity` (mlp). Google Play: `mlp_max_popularity` only (`all_time_max_popularity`).
- `impressions` — App Store: estimated daily impressions derived from both real and synthetic popularity. Google Play: `mlp_impressions` only.
- `difficulty` — both stores, single value (no real/mlp split).
- `language` — both stores, country-independent, single value.

**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). Duplicates are deduplicated.", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "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). Allowed values: `popularity`, `max_popularity`, `impressions`, `difficulty`, `language`.", "required": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "popularity", "max_popularity", "impressions", "difficulty", "language" ] }, "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.

**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" }, "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) belonging to the authenticated user. The `id` of each project is what every project-scoped endpoint (tracking, recommended-keywords, competitors) expects as `project_id`.

**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/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.

**Costs:** `max(10, ceil(returned / 100))` tokens — minimum 10 per call, then 1 extra token for every started bucket of 100 returned keywords.", "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": "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" ] } } }, { "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" ] } } } ], "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." }, "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`.

**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", "example": "photo editor" }, "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." }, "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.

**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", "example": "photo editor" }, "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." }, "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**.

**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" }, "example": "top-free" }, { "name": "category_key", "in": "query", "description": "Category key from `/v1/common-catalogs/categories`.", "required": true, "schema": { "type": "string" }, "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/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. Use it to enumerate the tracking set you're billing against, and to feed the `keyword_ids` parameter of the delete endpoint.

**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" } ], "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." }, "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.

**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", "example": "photo editor" }, "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiKeywordsLimitExceededSchema" } } } }, "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.

**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 }, "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." }, "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).

**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." }, "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.

**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", "example": "My folder" }, "description": { "type": "string", "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." }, "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.

**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 and/or updates its description. Omit a field to leave it unchanged. Returns 404 if the folder doesn't belong to any project of the authenticated user.

**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", "example": "Renamed folder" }, "description": { "type": "string", "example": "New description", "nullable": true } }, "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.

**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", "example": "photo editor" }, "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." }, "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.

**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 }, "keywords": { "type": "array", "items": { "type": "string", "example": "photo editor" }, "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." }, "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" } ] } } }, "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" }, "AppCommonInfoViewSchema": { "properties": { "app_info": { "properties": { "origin_id": { "type": "string", "example": "1234567890" }, "title": { "type": "string", "example": "My App" } }, "type": "object" } }, "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" }, "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" }, "PublicApiFolderNotFoundSchema": { "properties": { "error": { "type": "string", "example": "Folder not found" } }, "type": "object" }, "PublicApiInternalErrorSchema": { "properties": { "error": { "type": "string", "example": "Internal Server Error" } }, "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": { "type": "object", "allOf": [ { "properties": { "position": { "type": "integer", "example": 1 } }, "type": "object" }, { "$ref": "#/components/schemas/AppCommonInfoViewSchema" } ] }, "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" }, "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" }, "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": { "keywords": { "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" }, "PublicApiSuccessSchema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" }, "TrackKeywordsRankingResultViewSchema": { "properties": { "task_info": { "$ref": "#/components/schemas/TrackKeywordsRankingTaskInfoViewSchema" }, "response_data": { "properties": { "keywords_result": { "type": "object", "additionalProperties": { "schema": "TrackKeywordsRankingResultView", "properties": { "datetime": { "type": "string", "format": "date-time", "example": "2024-06-13T12:00:00+00:00" }, "positions": { "type": "array", "items": { "properties": { "position": { "type": "integer", "example": 1 }, "store_resource_id": { "type": "string", "example": "1234567890" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "TrackKeywordsRankingResultView": { "properties": { "datetime": { "type": "string", "format": "date-time", "example": "2024-06-13T12:00:00+00:00" }, "positions": { "type": "array", "items": { "properties": { "position": { "type": "integer", "example": 1 }, "store_resource_id": { "type": "string", "example": "1234567890" } }, "type": "object" } } }, "type": "object" }, "TrackKeywordsRankingTaskInfoViewSchema": { "properties": { "task_info": { "allOf": [ { "$ref": "#/components/schemas/StoreViewSchema" }, { "properties": { "id": { "type": "string", "example": "task-uuid" }, "custom_data": { "description": "Arbitrary key/value data echoed back from the request.", "type": "object", "example": { "client_request_id": "abc-123", "campaign": "spring-2026" }, "nullable": true, "additionalProperties": true }, "country": { "properties": { "code": { "type": "string", "example": "US" } }, "type": "object" }, "status": { "type": "string", "example": "PENDING" }, "keywords": { "properties": { "counts": { "properties": { "total": { "type": "integer", "example": 10 }, "paid": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] } }, "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" } }, "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": "Tracking Keywords", "description": "Tracking Keywords" }, { "name": "Tracking Folders", "description": "Tracking Folders" } ] }