Build with ASO Skill.

Make your first request.

For an AI agent or CLI, use browser-assisted login with the open-source ASO Skill CLI. It opens a connection page for you to approve the requested permissions, then stores the scoped credential in your operating-system credential store. No secret needs to be copied into .env or the conversation.

For a server or CI environment, create and store a key manually:

1. Create an account and accept the current terms.
2. Create a named API key in the dashboard. Its plaintext secret is shown once.
3. Store the key as ASO_SKILL_API_KEY in a server-side secret manager.
4. Send it as a Bearer credential from your server, script, agent runtime, or API client.

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"}'

Choose an endpoint.

Handle credits, freshness, and failures.

Every successful search, autocomplete, popularity, or app-lookup call costs one credit. Validation errors and upstream failures do not consume a credit; if a credit was reserved before a service failure, it is restored idempotently.

Search results are fresh for one hour and a stale search fallback is never older than 24 hours. Autocomplete terms are fresh for 30 days per storefront and platform. Compact app summaries used to enrich search results are reused for eight hours; if that optional enrichment is throttled, ranked results can still succeed with fewer optional fields. Popularity and app lookup results are fresh for eight hours. Low popularity may use a separate 30-day iPhone autocomplete summary; a long cold prefix curve can finish in the background. Preserve the response's cache, source, and fetchedAt fields when presenting data to a user.

A popularity source of autocomplete means an exact term appeared before the full query and conservatively raised a low result into the 6–10 band. It never lowers a stronger score or overrides monthly or uncensored direct data.

For HTTP 429 or a retryable 5xx response, honor Retry-After when present. Otherwise, retry with exponential backoff and jitter. Do not automatically repeat billing actions.

Responses advertise the enforced shared request policy through RateLimit-Policy and RateLimit-Limit. These are capacity hints, not additional credits or a per-account quota.

Plan for versions and deprecations.

The API encodes its major version in the URL. Existing /v1/ operations will not receive intentional breaking changes; backward-compatible additions may be released within v1. A breaking replacement will use a new major path such as /v2/.

When practical, a deprecated operation will remain available for at least six months. Its responses will include the standard Deprecation header, a Link to migration guidance with rel="deprecation", and, once removal is scheduled, a Sunset header. Deprecations will also be announced in this guide. Urgent security, legal, or upstream-platform requirements may require a shorter period.

Reference files and tools.

• OpenAPI 3.1 specification — operation IDs, typed schemas, authentication, and errors.
• llms.txt — product selection and resource discovery for agents.
• AI assistant guidance — interpretation, safety, and attribution guidance.
• API discovery document — the production interface and its public resources.
• Postman guide — an importable collection and interactive setup.