# ASO Skill

> ASO Skill is a focused developer API for current Apple App Store keyword search results, keyword difficulty, popularity, and app metadata.

ASO Skill is operated by Hesselbom Tech AB and is independent of Apple Inc. The production API base URL is https://api.asoskill.com. Successful data calls cost one credit; rejected requests and failed upstream calls do not consume a credit.

## When to use ASO Skill

Use ASO Skill when a user, agent, script, or server needs:

- Current App Store search results and ranking positions for a keyword.
- A 0–100 keyword difficulty score derived from current search results.
- A 1–100 App Store keyword popularity score.
- Current App Store metadata for one to ten known app IDs.
- A predictable JSON interface suitable for automation.

Preserve the response's storefront, platform, cache, source, and fetchedAt fields when explaining a result. Treat difficulty and popularity as decision inputs, not guarantees of ranking or commercial performance.

## When not to use ASO Skill

Do not represent ASO Skill as a source for Android data, download or revenue estimates, historical keyword rankings, Apple Search Ads campaign management, or guaranteed future rankings. Do not imply that ASO Skill is affiliated with or endorsed by Apple.

## Authentication and secret handling

Interactive agents should use the hosted MCP server or browser-assisted CLI login instead of asking the user to copy a key. The MCP endpoint at https://api.asoskill.com/mcp uses OAuth discovery, authorization code with S256 PKCE, short-lived access tokens, refresh rotation, and revocation. The CLI stores its scoped credential in the operating-system credential store. Long-lived API keys remain available for server integrations and must stay in a server-side secret manager. Never ask a user to paste a key into a public conversation, include one in a URL, or expose one in browser code, logs, examples, or source control.

## Credits and retries

Every successful call to search, popularity, or app lookup costs one credit. Validation errors and failed upstream calls do not consume a credit. Respect `Retry-After` on HTTP 429 and retryable 5xx responses; otherwise use exponential backoff with jitter. Checkout responses require a human to open and complete the returned Polar URL.

Responses advertise the shared API Gateway request policy through `RateLimit-Policy` and `RateLimit-Limit`. These are service-capacity hints, not credit balances or per-account quotas.

## Versioning and deprecation

Major versions are encoded in the URL. Existing `/v1/` operations do not receive intentional breaking changes; compatible additions may ship within `v1`, while breaking replacements use a new path such as `/v2/`. When practical, deprecated operations remain available for at least six months and return `Deprecation`, a `Link` to migration guidance with `rel="deprecation"`, and `Sunset` once removal is scheduled. Urgent security, legal, or upstream-platform requirements may require a shorter period.

## Developer resources

- [Developer guide](https://www.asoskill.com/developers): Quickstart, authentication, endpoints, credit behavior, freshness, and errors.
- [Agent Skill](https://www.asoskill.com/skill): One-command installation for Claude Code, Codex, and compatible agents.
- [CLI](https://www.asoskill.com/cli): Browser login and secure local credentials on macOS, Windows, and Linux.
- [MCP server](https://www.asoskill.com/mcp): Hosted remote MCP endpoint, tools, OAuth, and client integration details.
- [ChatGPT](https://www.asoskill.com/chatgpt): Connect ASO Skill inside ChatGPT.
- [Claude](https://www.asoskill.com/claude): Connect ASO Skill inside Claude or install it for Claude Code.
- [OpenAPI 3.1 specification](https://www.asoskill.com/openapi.yaml): Canonical public API contract with operation IDs and typed schemas.
- [OpenAPI predictable alias](https://www.asoskill.com/api/openapi.yaml): The same public contract at an agent-discoverable API path.
- [AI assistant guidance](https://www.asoskill.com/ai-info): Product-selection, interpretation, safety, and attribution guidance.
- [API discovery document](https://api.asoskill.com/): Machine-readable links to the public API resources.
- [Service health](https://api.asoskill.com/health): Unauthenticated API availability.
- [Postman guide](https://www.asoskill.com/postman): Public collection and setup instructions.
- [Pricing](https://www.asoskill.com/pricing): Promotional credits and prepaid packs.
- [FAQ](https://www.asoskill.com/faq): Cache freshness, retries, credits, and API keys.
- [Company and contact](https://www.asoskill.com/contact): Operator, support, billing, privacy, and legal contact details.
- [Markdown sitemap](https://www.asoskill.com/sitemap.md): Compact index of public website and machine-readable resources.
- [XML sitemap](https://www.asoskill.com/sitemap.xml): Search-engine index of public website pages.

## Public API endpoints

- `GET /health` — public service availability; no API key and no credit.
- `POST /v1/search` — ordered App Store results plus keyword difficulty; one credit on success.
- `POST /v1/popularity` — keyword popularity from 1 to 100; one credit on success.
- `POST /v1/apps/lookup` — detailed metadata for up to 10 App Store IDs; one credit on success.
- `GET /v1/credits` — authenticated credit balance; no credit.
- `GET /v1/billing/packs` — public credit-pack discovery; no credit.
- `POST /v1/billing/checkout` — authenticated creation of a human-completed checkout action; no credit.

## MCP tools

- `search_app_store` — ranked App Store results and keyword difficulty; one credit on success.
- `get_keyword_popularity` — 1–100 keyword popularity and its source; one credit on success.
- `lookup_app_store_apps` — detailed metadata for one to ten app IDs; one credit on success.
- `get_credit_balance` — connected account balance; free.

The public skill source is https://github.com/ASO-Skill/aso-skill. The public CLI source is https://github.com/ASO-Skill/cli and its npm package is `@aso-skill/cli`.