---
title: ASO Skill developer guide
description: Authentication, endpoints, credits, errors, and a quickstart for the ASO Skill Developer API.
canonical_url: https://www.asoskill.com/developers
md_url: https://www.asoskill.com/developers.md
---

# Build with ASO Skill

ASO Skill is a focused JSON API for current App Store keyword search, difficulty, popularity, and app metadata.

## Quickstart

For an agent or interactive CLI, use the [open-source ASO Skill CLI](https://github.com/ASO-Skill/cli), or start browser-assisted login through `POST /v1/auth/device`. Open the returned verification URL and let the account owner approve the exact requested scopes. Poll `POST /v1/auth/device/token`, decrypt its credential envelope with the local verifier, and save the credential in the operating-system credential store. Do not ask the user to copy it into `.env` or the conversation.

For a server or CI environment:

1. [Create an account](https://www.asoskill.com/api/auth/login) and accept the current terms.
2. Create a named API key in the developer dashboard. Its plaintext secret is shown once.
3. Store the key in a server-side secret manager as `ASO_SKILL_API_KEY`.
4. Call the production API with an Authorization Bearer header.

```sh
curl https://api.asoskill.com/v1/popularity \
  -H "Authorization: Bearer $ASO_SKILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"workout planner","storefront":"US"}'
```

## Endpoints

- `POST /v1/search`: current App Store results plus a 0–100 keyword difficulty score.
- `POST /v1/popularity`: a 1–100 keyword popularity score.
- `POST /v1/apps/lookup`: current metadata for one to ten App Store IDs.
- `GET /v1/credits`: the authenticated account's credit balance.
- `GET /v1/billing/packs`: public credit-pack discovery.
- `POST /v1/billing/checkout`: a human-completed Polar Checkout action.
- `GET /health`: public service availability.

## Authentication and safety

Data endpoints require a long-lived, scoped ASO Skill API key. Agent login should request `data` and `credits` by default; request `checkout` only when the user explicitly needs it. Keep the key in the operating-system credential store, on the server, or in a secret manager. Do not put it in browser JavaScript, URLs, logs, source control, `.env` generated through conversation, or chat transcripts. Keys remain valid until revoked or their optional expiration, and revocation can take up to five minutes to propagate.

## Credits, freshness, and errors

Every successful search, popularity, or app-lookup request costs one credit. Validation errors and upstream failures do not consume a credit; a reserved credit is restored idempotently after service failure. Search results are fresh for one hour, and a stale search fallback is never older than 24 hours. Compact app summaries used to enrich search results are reused for eight hours; if Apple throttles that optional enrichment, ranked results can still succeed with fewer optional fields. Popularity and app lookup results are fresh for eight hours. The response's `cache` and `fetchedAt` fields describe the returned observation.

For HTTP 429 or retryable 5xx responses, honor `Retry-After` when present. Otherwise retry with exponential backoff and jitter. Never automatically repeat non-idempotent billing actions.

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

## Versioning and deprecation policy

The API encodes its major version in the URL. Existing `/v1/` operations do not receive intentional breaking changes; backward-compatible additions may ship within `v1`. Breaking replacements use a new major path such as `/v2/`.

When practical, a deprecated operation remains available for at least six months. Deprecated responses include the standard `Deprecation` header, a `Link` to migration guidance with `rel="deprecation"`, and a `Sunset` header once removal is scheduled. Urgent security, legal, or upstream-platform requirements may require a shorter period.

## Machine-readable resources

- [OpenAPI 3.1 specification](https://www.asoskill.com/openapi.yaml)
- [Predictable OpenAPI URL](https://www.asoskill.com/api/openapi.yaml)
- [llms.txt](https://www.asoskill.com/llms.txt)
- [AI assistant guidance](https://www.asoskill.com/ai-info)
- [API discovery document](https://api.asoskill.com/)
- [Postman collection guide](https://www.asoskill.com/postman)
- [Markdown sitemap](https://www.asoskill.com/sitemap.md)

## Sitemap

See the [Markdown sitemap](https://www.asoskill.com/sitemap.md) for the complete public content index.