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. The tool opens a connection page, you approve its exact permissions, and it stores the resulting scoped credential in your operating-system credential store. You do not need to copy a secret into .env or into 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, 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. 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. Preserve the response's cache, source, and fetchedAt fields when presenting data to a user.

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.

Use the machine-readable resources.

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