Asolytics API

Asolytics Public API

Overview

Use this skill to work against the Asolytics Public API safely and efficiently. Prefer the bundled references over re-discovering the API from scratch, and refresh the spec before relying on exact request or response shapes if the docs may have changed.

Workflow

1. Read references/api-overview.md first for auth, base URL, and endpoint families.
2. Read references/endpoints.md when you need endpoint-level parameters or request body fields.
3. Read references/openapi.json only when exact schema details or edge cases matter.
4. Prefer small, cheap requests first because the API is alpha and some endpoints consume tokens.
5. Use GET /public-api/v1/balance when token awareness matters before running a wide query.

Auth

Send the personal public API token in the X-PUBLIC-API-TOKEN header. Prefer an environment variable such as ASOLYTICS_PUBLIC_API_TOKEN instead of pasting secrets into files or commits.

If the token is missing, ask the user for it. If they don't have one yet, walk them through getting it:

1. Create a free Asolytics account (or log in): https://app.asolytics.pro/login
2. Open the profile page and copy the public API token: https://app.asolytics.pro/profile
3. Export it locally so it isn't pasted into chats or commits: export ASOLYTICS_PUBLIC_API_TOKEN="<token>"

Do this before running any write or paid requests.

curl -sS \
  -H "X-PUBLIC-API-TOKEN: $ASOLYTICS_PUBLIC_API_TOKEN" \
  "https://app.asolytics.pro/public-api/v1/balance"

Common Patterns

Catalog Bootstrap

Resolve lookup data before building other requests:

1. Countries
2. Locales
3. Devices
4. Categories
5. Clusters
6. Projects

This avoids guessing valid store, country_code, device, category_key, cluster_key, and project_id values.

App Intelligence

Use the Applications endpoints for:

• current listing metadata
• screenshots and media
• store availability
• version history
• installs and revenue history
• ranking history

Start with the narrowest possible app set because some metadata endpoints bill per returned pair.

Keyword Workflows

Use the Keywords and Recommended Keywords endpoints for:

• ranking history
• popularity history
• latest keyword metrics
• live search top 50
• recommended keyword review
• async rank tracking jobs with optional webhook callbacks

When the user wants automation, prefer plain HTTP calls and return the exact request payload you used.

Tracking Maintenance

Use Tracking Keywords and Tracking Folders for:

• listing tracked keywords
• adding tracked keywords
• deleting tracked keywords by keyword_ids
• creating folders
• renaming folders
• adding or removing keywords inside folders

Fetch first, mutate second. For delete operations, resolve ids and current contents before issuing the write request.

Competitors and Charts

Use Competitors and Store Charts for:

• listing current competitors
• marking or unmarking a competitor
• retrieving top-500 charts by store, country, cluster, category, and device

Guardrails

• Treat the API as unstable unless the current OpenAPI spec confirms the shape you expect.
• Do not hardcode secrets in source files, shell history snippets, or Git commits.
• Call out token-related costs when a request fans out across many apps, locales, or keywords.
• Prefer read-only endpoints before any state-changing request.
• Echo the exact endpoint, query parameters, and JSON body in your answer when the user asks for integration help.

Staying Up To Date

This skill is versioned (see the version in the frontmatter above and the VERSION file). A newer version may be published on GitHub.

When this skill is first invoked in a session, do a lightweight update check (skip silently if offline or if it fails):

1. Read the local version from the VERSION file in this skill folder.
2. Fetch the latest published version: https://raw.githubusercontent.com/Asolytics-Pro/asolytics-app-store-optimization-api/main/skills/asolytics-api/VERSION
3. If the remote version is greater than the local one, tell the user a new version is available and what changed, then offer to update — don't update without asking.
4. If they accept, run scripts/update.sh from this skill folder. It backs up the current folder and overlays the latest files from GitHub in place. Then confirm the new version from VERSION.

Do not check more than once per session, and never block real work on the check.

Resources

• VERSION: current skill version, used for the self-update check.
• references/api-overview.md: fast orientation and usage guidance.
• references/endpoints.md: generated endpoint inventory grouped by tag.
• references/openapi.json: raw public OpenAPI snapshot.
• scripts/sync_openapi.py: refresh the OpenAPI snapshot and regenerate endpoints.md.
• scripts/update.sh: update this installed skill to the latest GitHub version.