# AsoBeast

> AsoBeast is an App Store Optimization (ASO) tool and keyword rank tracker for the Apple App Store and Google Play. Use the hosted service at https://asobeast.com or self host the open source edition.

- [AsoBeast documentation](https://docs.asobeast.com/index.md): AsoBeast is an App Store Optimization (ASO) tool and keyword rank tracker for the Apple App Store and Google Play. Use the hosted service at asobeast.com or self host the open source edition.
- [Quickstart](https://docs.asobeast.com/quickstart.md): Run asobeast with Docker Compose, create the owner account and import your first App Store or Google Play app in about five minutes.
- [System requirements](https://docs.asobeast.com/install/requirements.md): asobeast needs Docker with Compose, roughly 2.5 GB of memory and an outbound internet connection. PostgreSQL 18 and Redis 8 ship with the stack.
- [Self host with Docker Compose](https://docs.asobeast.com/install/docker-compose.md): Clone the repository, generate the two required secrets and run docker compose up. The API applies migrations and seeds the default workspace on first boot.
- [Deploy on Railway](https://docs.asobeast.com/install/railway.md): Deploy asobeast on Railway in one click. The template runs the published images with PostgreSQL and Redis and generates every secret for you.
- [Run a published release](https://docs.asobeast.com/install/published-images.md): Every GitHub release publishes multi architecture API and web images to GitHub Container Registry, tagged by version, minor, major, commit and latest.
- [Set up a development environment](https://docs.asobeast.com/install/local-development.md): Start PostgreSQL and Redis with the development Compose file, install with pnpm and run the API, the web app and the shared package together with pnpm dev.
- [Upgrade and roll back](https://docs.asobeast.com/install/upgrade.md): Pull the new image tag, restart the stack and let the API apply forward migrations on boot. Roll back by restoring a database backup taken before the upgrade.
- [How asobeast works](https://docs.asobeast.com/concepts/architecture.md): A Next.js frontend talks to a NestJS API over HTTP. Store collection runs in BullMQ workers behind a provider interface, and PostgreSQL holds the state.
- [Data model](https://docs.asobeast.com/concepts/data-model.md): An app is a single tracking entity with a home storefront. Keywords are scoped by text, store and country, so one app tracks keywords across many markets.
- [App Store and Google Play](https://docs.asobeast.com/concepts/stores.md): Apple indexes a title, a subtitle and a private 100 character keyword field. Google Play indexes the title, short description and long description.
- [Countries and markets](https://docs.asobeast.com/concepts/countries.md): An app is one row with a home storefront. Each tracked keyword carries its own country, one search serves the app and every competitor, and the listing is captured in every market you track.
- [Positions and rank depth](https://docs.asobeast.com/concepts/positions.md): Positions are 1 based. A null position means the keyword was checked and the app was not found within the captured depth, which defaults to 200.
- [Visibility](https://docs.asobeast.com/concepts/visibility.md): Visibility rolls the positions of an app's tracked keywords into one number from 0 to 100, each keyword weighted by its popularity and discounted by how far down the results it ranks.
- [Popularity, difficulty and opportunity](https://docs.asobeast.com/concepts/scoring.md): How popularity, difficulty and opportunity are calculated, what evidence each score carries, and when Apple's own search popularity replaces the estimate.
- [The daily pipeline and rate limits](https://docs.asobeast.com/concepts/pipeline.md): A daily cron enqueues rank checks, snapshots, reviews and category ranks. Two workers run at concurrency 1 behind per store rate limiters. A third reads screenshot text.
- [Import an app](https://docs.asobeast.com/guides/import-an-app.md): Search a store by name or paste an App Store or Google Play URL, and asobeast captures the first snapshot, extracts keywords and tracks them in the home storefront.
- [Track keywords](https://docs.asobeast.com/guides/track-keywords.md): Add keywords per storefront on the keyword monitor, import a list from a CSV file, see which keyword fields each market reads, and know what every added market costs in daily store requests.
- [Read rankings and SERPs](https://docs.asobeast.com/guides/read-rankings.md): The ranking chart uses a reversed Y axis so position 1 sits at the top. SERP snapshots keep the top 10 results per keyword and per day.
- [Track competitors](https://docs.asobeast.com/guides/competitors.md): Add a competitor by name, from a store URL, from a stored SERP snapshot or from the suggestions in the guided setup. Competitors cost no extra store requests on keywords you already track.
- [Run an ASO audit](https://docs.asobeast.com/guides/aso-audit.md): The audit scores a listing against a deterministic, store specific rubric, weights every factor by how much of it could be measured, and turns what fails into a ranked plan.
- [Optimize listing metadata](https://docs.asobeast.com/guides/metadata-workbench.md): The workbench lints each indexed field against its store limit, reports keyword coverage, and holds the App Store localizations of an app with one private iOS keyword field each.
- [Read screenshot captions](https://docs.asobeast.com/guides/screenshot-captions.md): asobeast reads the large caption text printed on App Store screenshots on your own machine, shows it per screenshot, reports it beside keyword coverage and records screenshot and caption edits as change events.
- [Sync reviews, reply to them and mine keyword ideas](https://docs.asobeast.com/guides/reviews.md): Reviews sync in the daily pipeline for the home storefront. See what people mention, translate a review, draft and track a reply to each one, and turn repeated language in negative reviews into keyword ideas and action items.
- [Watch listing changes](https://docs.asobeast.com/guides/listing-changes.md): Every snapshot is compared with the previous one, so a changed title, subtitle or description becomes a dated event for your apps and competitors, and each change to your own listing is measured against your keyword positions.
- [Read impressions and conversion from your console](https://docs.asobeast.com/guides/store-funnel.md): Connect an App Store Connect key or a Google Play service account once and see the store's own funnel by market beside your rankings: impressions, page views, Get taps and conversion on the App Store, store listing visitors, acquisitions and installs per search term on Google Play.
- [Work the Action Center](https://docs.asobeast.com/guides/action-center.md): Seventeen deterministic rules run over your stored history and return a prioritized queue, each recommendation carrying the exact numbers behind it, its history and, once done, its measured outcome.
- [Follow category ranks](https://docs.asobeast.com/guides/category-ranks.md): asobeast captures free, paid and grossing chart positions daily for the home storefront, so a chart move reads alongside keyword positions.
- [Read top charts](https://docs.asobeast.com/guides/top-charts.md): Read the free, paid and grossing charts of any storefront and category side by side, see who climbed, entered, fell and dropped out, follow a category and capture today on demand.
- [Compare a portfolio](https://docs.asobeast.com/guides/portfolio.md): Read the dashboard, link the App Store and Google Play listings of one product into a group, compare visibility across it and receive a weekly portfolio digest.
- [Send alerts](https://docs.asobeast.com/guides/alerts.md): asobeast delivers rank, SERP, metadata, review and action events by signed webhook or SMTP email. Batched delivery is resumable and deduplicated.
- [Connect a chat tool](https://docs.asobeast.com/guides/alert-channels.md): Send AsoBeast reports to Discord, Slack, Microsoft Teams, Telegram or Google Chat by pasting the webhook url the tool gives you.
- [Enable the optional AI features](https://docs.asobeast.com/guides/ai-features.md): Set OPENAI_API_KEY to enable the AI creative analysis, metadata drafts, action explanations, review reply drafts and review translations. Every other feature works with the key left unset.
- [Export data](https://docs.asobeast.com/guides/export-data.md): The keyword monitor, rankings view, competitors page, reviews list and top 10 sheet export CSV, and the overview and the rankings view print as a report you can save as PDF. Each file follows the filters you applied.
- [Configuration reference](https://docs.asobeast.com/configuration/reference.md): Every environment variable the asobeast API reads, with its default and its effect. AUTH_SECRET is required and must be at least 32 characters.
- [Web app configuration](https://docs.asobeast.com/configuration/web.md): The web app reads API_INTERNAL_URL and TRUST_PROXY at runtime and proxies browser traffic to the API, so one image can target any API without a rebuild.
- [Authentication and accounts](https://docs.asobeast.com/security/authentication.md): Every request is authenticated. The first account on a fresh instance becomes the owner, and registration closes automatically afterwards.
- [Account recovery](https://docs.asobeast.com/security/account-recovery.md): A customer who forgot their password recovers by email, without the operator touching the database.
- [Personal API tokens](https://docs.asobeast.com/security/api-tokens.md): Mint a revocable personal API token in Integrations and send it as a bearer header. The plaintext value is shown once and stored only as a hash.
- [Store console credentials](https://docs.asobeast.com/security/store-credentials.md): What asobeast stores when an owner connects an App Store Connect key or a Google Play service account, how the key is sealed at rest, who can use it and how to revoke it or rotate the encryption key.
- [Hosting behind TLS and a reverse proxy](https://docs.asobeast.com/security/hosting.md): Reach the stack through a Cloudflare Tunnel or your own reverse proxy, set AUTH_COOKIE_SECURE to true, and verify TRUST_PROXY against the real chain.
- [The queue dashboard and the OpenAPI surface](https://docs.asobeast.com/security/admin-surfaces.md): The queue dashboard, the OpenAPI routes, the metrics scrape and the operator endpoints answer 404 to anyone who is not the platform operator, and the admin pages show the app's not found view.
- [Health checks and monitoring](https://docs.asobeast.com/operations/health-checks.md): The API health endpoint reports the database, Redis, the last daily pipeline run, the failed job count and the open action count in one response.
- [Uptime probes and the status page](https://docs.asobeast.com/operations/uptime.md): Every alert asobeast evaluates runs inside asobeast. Something outside the machine has to watch it, and customers need somewhere to look when the answer is no.
- [Upgrade an installation](https://docs.asobeast.com/operations/upgrades.md): Which versions upgrade directly to the current release, what the API container does to your database on boot, how the upgrade path is proven in CI before it reaches you, and how to recover when a migration fails.
- [Back up PostgreSQL](https://docs.asobeast.com/operations/backups.md): PostgreSQL is the durable system of record, so it is the only thing that needs backing up. Redis holds reconstructible queue state only.
- [Restore PostgreSQL](https://docs.asobeast.com/operations/restore.md): Restoring replaces the current database. Stop the applications, drop and recreate it, restore the verified archive, then check both health endpoints.
- [Rotate secrets](https://docs.asobeast.com/operations/rotate-secrets.md): Rotating AUTH_SECRET signs out every session but leaves personal API tokens working. The database password needs an alter role statement.
- [Email deliverability](https://docs.asobeast.com/operations/email-deliverability.md): Make account and alert emails reach the inbox: authenticate the sending domain with SPF, DKIM and DMARC, and keep one click unsubscribe working.
- [Recover a wedged release](https://docs.asobeast.com/operations/release-recovery.md): Two ways a release stops shipping: Release Please advances the version manifest without creating the tag, or no workflow starts at all. Recognize each, then finish the release by hand.
- [How much can one instance collect?](https://docs.asobeast.com/operations/capacity.md): Measured orchestration cost and projected daily wall clock at three scales, the configuration where a run stops finishing inside a day, and what the per market multiplier really costs.
- [Billing and the subscription lifecycle](https://docs.asobeast.com/operations/billing.md): How a hosted workspace moves from trial to paid, what happens when a card fails, and what a downgrade or cancellation does to the data already collected.
- [Take billing live](https://docs.asobeast.com/operations/billing-go-live.md): The dashboard settings the API cannot reach, the ordered steps from a sandbox to live mode, and how to roll back if the first live payment goes wrong.
- [Recover from a broken store parser](https://docs.asobeast.com/operations/scraper-breakage.md): Apple and Google can change a response shape without notice. Recognize it, tell it apart from rate limiting, contain it, and ship the one module change that fixes it.
- [Connect Apple Ads](https://docs.asobeast.com/operations/apple-ads.md): Give asobeast an Apple Ads API key so App Store popularity uses Apple's own weekly search popularity where Apple publishes it. Optional and off by default.
- [Troubleshooting](https://docs.asobeast.com/operations/troubleshooting.md): Twenty symptoms a self hosted asobeast instance produces, each with its cause and its fix, from a stack that refuses to start to alerts that never arrive.
- [Observability for a hosted instance](https://docs.asobeast.com/operations/hosted-observability.md): Structured logs, per workspace metrics, the alert catalogue and the support surface. What a hosted operator watches, and where each signal comes from.
- [Proxy pool degradation](https://docs.asobeast.com/operations/runbooks/proxy-pool-degradation.md): Healthy endpoints fall below the threshold. Tell blocking apart from a transport fault, decide between waiting, buying more and falling back, and recover without burning residential budget.
- [Daily run overrun](https://docs.asobeast.com/operations/runbooks/daily-run-overrun.md): The daily run did not finish before the next trigger. Decide whether to skip, resume or truncate, and keep one heavy tenant from starving everyone else.
- [Store parser breakage on the hosted service](https://docs.asobeast.com/operations/runbooks/hosted-parser-breakage.md): A store changed its response shape and every customer is affected at once. Communication comes first, the one module fix comes second.
- [Billing incident](https://docs.asobeast.com/operations/runbooks/billing-incident.md): Webhooks are failing, or a customer is wrongly locked out or wrongly served. Reconcile against the provider rather than editing plans by hand.
- [Suspected isolation incident](https://docs.asobeast.com/operations/runbooks/isolation-incident.md): One workspace may have seen another's data. Contain, assess the scope, then notify. Written before it is needed, because disclosure has deadlines.
- [Capacity exhaustion](https://docs.asobeast.com/operations/runbooks/capacity-exhaustion.md): Demand is approaching the pool ceiling. Gate registration rather than degrade the customers who already pay.
- [Pricing](https://docs.asobeast.com/legal/pricing.md): Two hosted plans, the exact limits the code enforces, and the self hosted option that costs nothing and has the same features.
- [Terms of service](https://docs.asobeast.com/legal/terms.md): The terms of the hosted asobeast service are published at asobeast.com/terms. A self hosted installation is governed by AGPL-3.0-only alone.
- [Privacy policy](https://docs.asobeast.com/legal/privacy.md): The privacy policy of the hosted asobeast service is published at asobeast.com/privacy. A self hosted installation collects nothing and reports to nobody.
- [Subprocessors](https://docs.asobeast.com/legal/subprocessors.md): Every third party the hosted asobeast service sends data to, what reaches each one, and which of them a self hosted installation uses.
- [Data export, deletion and retention](https://docs.asobeast.com/legal/data-retention.md): Export every row your workspace owns, delete the workspace with a reversible grace period, and read the two honest limits on what deletion can reach.
- [How asobeast collects data](https://docs.asobeast.com/legal/data-collection.md): What the service reads from Apple and Google, what it refuses to do, why the self hosted and hosted cases differ, and what happens if a store objects.
- [Glossary](https://docs.asobeast.com/glossary.md): Definitions of the ASO and asobeast terms used across this documentation, from home storefront and keyword field to opportunity and fingerprint.
- [Changelog](https://docs.asobeast.com/changelog.md): Release Please owns versions, tags and CHANGELOG.md for asobeast, and every release publishes multi architecture container images to GHCR.
- [Get help](https://docs.asobeast.com/support.md): Open a GitHub issue for bugs, start a discussion for questions, and read the security policy before reporting a vulnerability privately.
- [asobeast API](https://docs.asobeast.com/api-reference/introduction.md): The asobeast API is a REST API over HTTP. Every endpoint requires authentication with a session cookie or a personal API token, and every response is JSON.
- [Authenticate API requests](https://docs.asobeast.com/api-reference/authentication.md): Send a personal API token as a bearer header on every request. Create the token in Integrations, where it is shown once and prefixed with asob_.
- [Error responses](https://docs.asobeast.com/api-reference/errors.md): Every failure returns the same JSON envelope with a status code, message, path and timestamp. Validation failures return 400 with the failing fields.
- [Rate limits and quotas](https://docs.asobeast.com/api-reference/rate-limits.md): Limits are per workspace and sized per plan across three request classes. Every response carries RateLimit headers, and a 429 names the window that closed.
- [API conventions](https://docs.asobeast.com/api-reference/conventions.md): Dates are UTC and daily granularity uses a date string. Positions are 1 based and null means checked and not found. Queued operations return 202.
- [Register an account](https://docs.asobeast.com/api-reference/auth/register-an-account.md)
- [Log in](https://docs.asobeast.com/api-reference/auth/log-in.md)
- [Log out](https://docs.asobeast.com/api-reference/auth/log-out.md)
- [Current authenticated user](https://docs.asobeast.com/api-reference/auth/current-authenticated-user.md)
- [Workspace plan, limits and usage against them](https://docs.asobeast.com/api-reference/auth/workspace-plan-limits-and-usage-against-them.md)
- [Confirm an email address and start the trial](https://docs.asobeast.com/api-reference/auth/confirm-an-email-address-and-start-the-trial.md)
- [Send a fresh confirmation link to this account](https://docs.asobeast.com/api-reference/auth/send-a-fresh-confirmation-link-to-this-account.md)
- [Change password and reset other sessions](https://docs.asobeast.com/api-reference/auth/change-password-and-reset-other-sessions.md)
- [Email a recovery link to an account that exists](https://docs.asobeast.com/api-reference/auth/email-a-recovery-link-to-an-account-that-exists.md)
- [Redeem a recovery link and end every session](https://docs.asobeast.com/api-reference/auth/redeem-a-recovery-link-and-end-every-session.md)
- [Public auth configuration and session state](https://docs.asobeast.com/api-reference/auth/public-auth-configuration-and-session-state.md)
- [List personal api tokens](https://docs.asobeast.com/api-reference/auth/list-personal-api-tokens.md)
- [Create a personal api token](https://docs.asobeast.com/api-reference/auth/create-a-personal-api-token.md)
- [Revoke a personal api token](https://docs.asobeast.com/api-reference/auth/revoke-a-personal-api-token.md)
- [Members of this workspace and pending invites](https://docs.asobeast.com/api-reference/auth/members-of-this-workspace-and-pending-invites.md)
- [Invite a member into this workspace](https://docs.asobeast.com/api-reference/auth/invite-a-member-into-this-workspace.md)
- [Revoke a pending invitation](https://docs.asobeast.com/api-reference/auth/revoke-a-pending-invitation.md)
- [Remove a member from this workspace](https://docs.asobeast.com/api-reference/auth/remove-a-member-from-this-workspace.md)
- [Accept an invitation and create the account](https://docs.asobeast.com/api-reference/auth/accept-an-invitation-and-create-the-account.md)
- [Whether the optional AI features are configured](https://docs.asobeast.com/api-reference/ai/whether-the-optional-ai-features-are-configured.md)
- [List configured alert webhooks](https://docs.asobeast.com/api-reference/webhooks/list-configured-alert-webhooks.md)
- [Register an alert webhook](https://docs.asobeast.com/api-reference/webhooks/register-an-alert-webhook.md)
- [Delete an alert webhook](https://docs.asobeast.com/api-reference/webhooks/delete-an-alert-webhook.md)
- [Update an alert webhook](https://docs.asobeast.com/api-reference/webhooks/update-an-alert-webhook.md)
- [Send a sample payload to a webhook](https://docs.asobeast.com/api-reference/webhooks/send-a-sample-payload-to-a-webhook.md)
- [List configured email alerts](https://docs.asobeast.com/api-reference/email-alerts/list-configured-email-alerts.md)
- [Register an email alert](https://docs.asobeast.com/api-reference/email-alerts/register-an-email-alert.md)
- [Delete an email alert](https://docs.asobeast.com/api-reference/email-alerts/delete-an-email-alert.md)
- [Update an email alert](https://docs.asobeast.com/api-reference/email-alerts/update-an-email-alert.md)
- [Send a sample email to a confirmed alert recipient](https://docs.asobeast.com/api-reference/email-alerts/send-a-sample-email-to-a-confirmed-alert-recipient.md)
- [Send the recipient a new confirmation email](https://docs.asobeast.com/api-reference/email-alerts/send-the-recipient-a-new-confirmation-email.md)
- [Confirm an alert recipient from the link in the confirmation email](https://docs.asobeast.com/api-reference/email-alerts/confirm-an-alert-recipient-from-the-link-in-the-confirmation-email.md)
- [Stop one email alert from the link in its own message (RFC 8058 one click)](https://docs.asobeast.com/api-reference/email-alerts/stop-one-email-alert-from-the-link-in-its-own-message-rfc-8058-one-click.md)
- [Probe which alert channels are available](https://docs.asobeast.com/api-reference/alerts/probe-which-alert-channels-are-available.md)
- [Report the alert delivery mode and outbox status](https://docs.asobeast.com/api-reference/alerts/report-the-alert-delivery-mode-and-outbox-status.md)
- [Flush the alert outbox into grouped deliveries](https://docs.asobeast.com/api-reference/alerts/flush-the-alert-outbox-into-grouped-deliveries.md)
- [List recent alert deliveries for one channel](https://docs.asobeast.com/api-reference/alerts/list-recent-alert-deliveries-for-one-channel.md)
- [Liveness, database and pipeline health check](https://docs.asobeast.com/api-reference/health/liveness-database-and-pipeline-health-check.md)
- [Manually run the daily pipeline for one app](https://docs.asobeast.com/api-reference/jobs/manually-run-the-daily-pipeline-for-one-app.md)
- [Report what a newly imported app is still waiting for](https://docs.asobeast.com/api-reference/jobs/report-what-a-newly-imported-app-is-still-waiting-for.md)
- [Today's run of one app](https://docs.asobeast.com/api-reference/jobs/todays-run-of-one-app.md): Counts, for one app, the listings captured for the app and its competitors in the home storefront and every tracked market, the active keywords whose position was checked and the category charts read against the charts the app is ranked in (the chart of its price class and the grossing chart, each i…
- [Estimate the daily store request budget](https://docs.asobeast.com/api-reference/jobs/estimate-the-daily-store-request-budget.md)
- [Progress of this workspace's own daily run](https://docs.asobeast.com/api-reference/jobs/progress-of-this-workspaces-own-daily-run.md)
- [Report whether each store still parses](https://docs.asobeast.com/api-reference/jobs/report-whether-each-store-still-parses.md)
- [Total daily demand against pool capacity](https://docs.asobeast.com/api-reference/admin/total-daily-demand-against-pool-capacity.md)
- [Egress proxy pool health for operators](https://docs.asobeast.com/api-reference/admin/egress-proxy-pool-health-for-operators.md)
- [List every workspace with its operational state](https://docs.asobeast.com/api-reference/admin/list-every-workspace-with-its-operational-state.md)
- [Operational detail for one workspace](https://docs.asobeast.com/api-reference/admin/operational-detail-for-one-workspace.md)
- [Reconcile one workspace against the billing provider](https://docs.asobeast.com/api-reference/admin/reconcile-one-workspace-against-the-billing-provider.md)
- [Replay a stored billing event for this workspace](https://docs.asobeast.com/api-reference/admin/replay-a-stored-billing-event-for-this-workspace.md)
- [Suspend a workspace](https://docs.asobeast.com/api-reference/admin/suspend-a-workspace.md)
- [Restore a suspended workspace](https://docs.asobeast.com/api-reference/admin/restore-a-suspended-workspace.md)
- [Queue the daily run for one workspace](https://docs.asobeast.com/api-reference/admin/queue-the-daily-run-for-one-workspace.md)
- [Instance totals for the platform operator](https://docs.asobeast.com/api-reference/admin/instance-totals-for-the-platform-operator.md)
- [Every account on the instance, newest first](https://docs.asobeast.com/api-reference/admin/every-account-on-the-instance-newest-first.md)
- [Every tracked app on the instance, newest first](https://docs.asobeast.com/api-reference/admin/every-tracked-app-on-the-instance-newest-first.md)
- [Enqueue an on demand keyword score](https://docs.asobeast.com/api-reference/scoring/enqueue-an-on-demand-keyword-score.md)
- [Stream every row this workspace owns as newline delimited JSON](https://docs.asobeast.com/api-reference/account/stream-every-row-this-workspace-owns-as-newline-delimited-json.md)
- [Whether this workspace is scheduled for deletion](https://docs.asobeast.com/api-reference/account/whether-this-workspace-is-scheduled-for-deletion.md)
- [Schedule this workspace for deletion after a grace period](https://docs.asobeast.com/api-reference/account/schedule-this-workspace-for-deletion-after-a-grace-period.md)
- [Cancel a scheduled deletion during its grace period](https://docs.asobeast.com/api-reference/account/cancel-a-scheduled-deletion-during-its-grace-period.md)
- [Plans available to buy and their price ids](https://docs.asobeast.com/api-reference/billing/plans-available-to-buy-and-their-price-ids.md)
- [Start a Stripe Checkout session for a plan](https://docs.asobeast.com/api-reference/billing/start-a-stripe-checkout-session-for-a-plan.md)
- [Open the Stripe customer portal for this workspace](https://docs.asobeast.com/api-reference/billing/open-the-stripe-customer-portal-for-this-workspace.md)
- [Reconcile this workspace against Stripe now](https://docs.asobeast.com/api-reference/billing/reconcile-this-workspace-against-stripe-now.md)
- [List imported apps](https://docs.asobeast.com/api-reference/apps/list-imported-apps.md)
- [Import an app from a store URL](https://docs.asobeast.com/api-reference/apps/import-an-app-from-a-store-url.md)
- [Get an app with its latest snapshot and competitors](https://docs.asobeast.com/api-reference/apps/get-an-app-with-its-latest-snapshot-and-competitors.md)
- [Delete an app](https://docs.asobeast.com/api-reference/apps/delete-an-app.md)
- [List the markets an app has a captured listing in](https://docs.asobeast.com/api-reference/apps/list-the-markets-an-app-has-a-captured-listing-in.md)
- [Probe whether an app is published in a storefront](https://docs.asobeast.com/api-reference/apps/probe-whether-an-app-is-published-in-a-storefront.md)
- [Refresh an app and return the snapshot diff](https://docs.asobeast.com/api-reference/apps/refresh-an-app-and-return-the-snapshot-diff.md)
- [Link an app to its counterpart on the other store](https://docs.asobeast.com/api-reference/apps/link-an-app-to-its-counterpart-on-the-other-store.md)
- [Unlink an app from its group](https://docs.asobeast.com/api-reference/apps/unlink-an-app-from-its-group.md)
- [Read the guided setup of an app](https://docs.asobeast.com/api-reference/apps/read-the-guided-setup-of-an-app.md): The status, the skipped steps, whether countries were reviewed and the selected markets of the guided setup, kept on the account so every member and every device sees the same progress. An import starts it in progress; a primary app without a row answers not_started with its home market selected and…
- [Update the guided setup of an app](https://docs.asobeast.com/api-reference/apps/update-the-guided-setup-of-an-app.md): Changes the fields given and keeps the rest; an empty body changes nothing. Skipped steps are stored in step order. completed stamps completedAt once and keeps that time when completed again; any other status clears it. Answers 400 for an unknown status or step, a repeated step or market, a market t…
- [Queue lookups that detect the localizations an app ships](https://docs.asobeast.com/api-reference/apps/queue-lookups-that-detect-the-localizations-an-app-ships.md): Takes the localizations the markets of the app read, drops the ones the app ships and, when the home listing declares its languages, the ones in languages it does not declare, then queues one deferred store lookup per remaining localization in the first market that has a stored default listing and c…
- [Seed a market with the keywords of its own listing](https://docs.asobeast.com/api-reference/apps/seed-a-market-with-the-keywords-of-its-own-listing.md): Captures the listing of the app in one storefront now, extracts the title and subtitle phrases of that listing, of its native localizations and of every localization the app ships that the storefront reads besides its default, tracks up to 15 of them in that market as listing keywords within the key…
- [Suggest storefronts from the languages the home listing declares](https://docs.asobeast.com/api-reference/apps/suggest-storefronts-from-the-languages-the-home-listing-declares.md): Reads the languages the newest home listing declares and answers every App Store storefront that reads a localization in one of them, the home storefront left out, with the localization, its role in that storefront (default or additional), whether the app already tracks keywords there and the daily…
- [Search a store by app name](https://docs.asobeast.com/api-reference/apps/search-a-store-by-app-name.md): Lists up to 25 listings the store returns for a name in one storefront, with the store app id, title, developer, rating and icon, so an app or a competitor can be picked by name before it is imported or added by its id. Reaches the store while you wait, so it answers within the store deadline and sp…
- [List tracked keywords for an app](https://docs.asobeast.com/api-reference/keywords/list-tracked-keywords-for-an-app.md)
- [Add manual keywords](https://docs.asobeast.com/api-reference/keywords/add-manual-keywords.md)
- [List the markets an app tracks keywords in](https://docs.asobeast.com/api-reference/keywords/list-the-markets-an-app-tracks-keywords-in.md)
- [Compare keyword positions against competitors](https://docs.asobeast.com/api-reference/keywords/compare-keyword-positions-against-competitors.md): One row per active tracked keyword, in every market it is tracked in. you and each value of positions are the latest position, 1 based; null means the app was checked and not found within the captured depth. unchecked lists the ids of the apps, the app itself and its competitors, that have no record…
- [Show how the listing of an app and of each competitor matches one tracked keyword](https://docs.asobeast.com/api-reference/keywords/show-how-the-listing-of-an-app-and-of-each-competitor-matches-one-tracked-keyword.md): Reads stored data only and makes no store request. The app comes first, then every competitor. words are the distinct words of the keyword. Each listing is one localization the keyword market searches (localization and role are null on Google Play), judged field by field: phrase is the verdict of th…
- [Suggest keywords from metadata, the store, competitors, seasons or reviews](https://docs.asobeast.com/api-reference/keywords/suggest-keywords-from-metadata-the-store-competitors-seasons-or-reviews.md)
- [Aggregate suggest spider probes for a term](https://docs.asobeast.com/api-reference/keywords/aggregate-suggest-spider-probes-for-a-term.md)
- [Enqueue suggest spider probes for a term](https://docs.asobeast.com/api-reference/keywords/enqueue-suggest-spider-probes-for-a-term.md)
- [Preview a keyword import without writing](https://docs.asobeast.com/api-reference/keywords/preview-a-keyword-import-without-writing.md): Validates up to 500 rows and answers, for every row, whether an import would track it, resume it, skip it or refuse it, with the daily store requests the import would add and the keyword limit of the plan. Writes nothing and queues nothing. Rows without a country use the request country, which is a…
- [Import keywords with tags, notes and markets](https://docs.asobeast.com/api-reference/keywords/import-keywords-with-tags-notes-and-markets.md): Tracks every row that is new or paused, up to 500 rows, in one transaction, with its tags and note, as manual keywords, and queues each new keyword for its first score. Rows that are invalid, duplicated, already tracked or over the plan keyword limit are reported per row and skipped. Rows that are a…
- [Stop tracking a keyword](https://docs.asobeast.com/api-reference/keywords/stop-tracking-a-keyword.md)
- [Update a tracked keyword active flag or relevance](https://docs.asobeast.com/api-reference/keywords/update-a-tracked-keyword-active-flag-or-relevance.md)
- [Read a stored iOS keyword field](https://docs.asobeast.com/api-reference/keywords/read-a-stored-ios-keyword-field.md): Returns the keyword field of one App Store localization: phrases is the field as saved, in order, and tracked is those of its phrases tracked and active in country. Without a query it reads the home storefront's default localization. duplicatesRemoved is always 0 because a read discards nothing.
- [Set an iOS keyword field](https://docs.asobeast.com/api-reference/keywords/set-an-ios-keyword-field.md): Replaces the keyword field of one App Store localization with the normalized, deduplicated phrases of text, tracks them in country, and returns the stored field. Without a query it sets the home storefront's default localization. Answers 400 when the storefront does not read the localization, or whe…
- [List the stored iOS keyword fields](https://docs.asobeast.com/api-reference/keywords/list-the-stored-ios-keyword-fields.md): Returns every saved keyword field of the app, one per App Store localization, with the markets of the app that read it.
- [List the App Store localizations an app ships](https://docs.asobeast.com/api-reference/keywords/list-the-app-store-localizations-an-app-ships.md): Returns the default localization of the home storefront, every localization added by hand or detected, and every localization with a saved keyword field, the home localization first and the rest by display name. Each item carries its keyword field and the markets of the app that read it, with the ro…
- [Add an App Store localization to an app](https://docs.asobeast.com/api-reference/keywords/add-an-app-store-localization-to-an-app.md): Marks one of the 50 App Store localizations as shipped by the app, with no keyword field yet, and answers 201 with the item. Answers 409 when the app already ships it, the default localization of the home storefront included, and 400 for a tag outside the 50 or a Google Play or competitor app.
- [Remove an App Store localization from an app](https://docs.asobeast.com/api-reference/keywords/remove-an-app-store-localization-from-an-app.md): Removes a shipped localization and its keyword field in one transaction. Each phrase of the field stops being tracked as a keyword field phrase in every market that reads the localization, unless another saved field there holds it. Keywords tracked from another source stay tracked. Answers 204, 409…
- [Read what one market search reads](https://docs.asobeast.com/api-reference/keywords/read-what-one-market-search-reads.md): Answers every localization the storefront of the market reads, in read order, with its role (default or additional), whether the app ships it, its origin (home, manual or detected, null when it is not shipped), its saved phrases and the characters they use. Without a query it describes the home stor…
- [Save the keyword field of one localization](https://docs.asobeast.com/api-reference/keywords/save-the-keyword-field-of-one-localization.md): Replaces the keyword field of one App Store localization with the normalized, deduplicated phrases of text, ships the localization when it is not shipped yet, and tracks every phrase in each market of trackIn. trackIn may be empty and must name only markets of the app whose storefront reads the loca…
- [Preview saving the keyword field of one localization](https://docs.asobeast.com/api-reference/keywords/preview-saving-the-keyword-field-of-one-localization.md): Answers, for every market of the app whose storefront reads the localization, the phrases the field would add to the tracked keywords, how many of them would open a new keyword market and the daily store requests that costs, plus the phrases the save would add to and drop from the stored field and t…
- [Metadata change timeline for an app and its competitors](https://docs.asobeast.com/api-reference/changes/metadata-change-timeline-for-an-app-and-its-competitors.md)
- [Keyword position and visibility movement after each change to an app listing](https://docs.asobeast.com/api-reference/changes/keyword-position-and-visibility-movement-after-each-change-to-an-app-listing.md)
- [Recent metadata changes across the workspace](https://docs.asobeast.com/api-reference/changes/recent-metadata-changes-across-the-workspace.md)
- [The store consoles this workspace has connected](https://docs.asobeast.com/api-reference/store-connect/the-store-consoles-this-workspace-has-connected.md): Every connected store console key with its status, the access its report requests were granted, and each primary app of that store with its report state and the first and last day of stored funnel rows. Never returns key material. available is false when the instance has no STORE_CONNECT_ENCRYPTION_…
- [Connect a store console key](https://docs.asobeast.com/api-reference/store-connect/connect-a-store-console-key.md): Verifies the key with the store, seals it at rest bound to this workspace and replaces any key connected before, then queues a report sync. App Store Connect takes an issuer ID, a key ID and a .p8 private key; Google Play takes a service account JSON key and the bucket id of its Play Console reports…
- [Disconnect a store console](https://docs.asobeast.com/api-reference/store-connect/disconnect-a-store-console.md): Deletes the sealed key and its report requests, even while the instance has store connections off. The funnel rows already stored stay.
- [Verify the connected store console key again](https://docs.asobeast.com/api-reference/store-connect/verify-the-connected-store-console-key-again.md): Asks the store whether the stored key still works. A refused key marks the connection rejected; an accepted one clears that and queues a report sync. Answers 409 when the stored key can no longer be decrypted.
- [Queue a report sync for the connected store console](https://docs.asobeast.com/api-reference/store-connect/queue-a-report-sync-for-the-connected-store-console.md): Queues the download of the reports the store has published since the last sync. A sync already waiting is not queued twice. Answers 409 while the store refuses the key.
- [Start connecting Google Play with a Google account](https://docs.asobeast.com/api-reference/store-connect/start-connecting-google-play-with-a-google-account.md): Answers the Google consent address to send the owner to, asking for read only Cloud Storage access, with a state sealed to this owner and workspace that expires in ten minutes. Google returns to the web page /integrations/google-play. Owner only, through a signed in session. Answers 409 when the ins…
- [Finish connecting Google Play with a Google account](https://docs.asobeast.com/api-reference/store-connect/finish-connecting-google-play-with-a-google-account.md): Redeems the code Google returned, lists the bucket with the account before anything is stored, seals the refresh token bound to this workspace, replaces any Google Play connection and queues a report sync. Answers 400 for a state of another owner, an expired state or a code Google refuses, 422 when…
- [Store impressions, page views, downloads and conversion of an app by market and window](https://docs.asobeast.com/api-reference/store-connect/store-impressions-page-views-downloads-and-conversion-of-an-app-by-market-and-window.md): Reads the rows the connected store console reported: a zero filled daily series of the requested days with the total and the search share, and the 7, 14 and 28 day windows of complete days against the period before. A day is complete once it is three days old and the store has delivered it. Answers…
- [Screenshots of the latest snapshot of a listing with the caption read from each](https://docs.asobeast.com/api-reference/screenshots/screenshots-of-the-latest-snapshot-of-a-listing-with-the-caption-read-from-each.md)
- [Ranking history series for an app](https://docs.asobeast.com/api-reference/rankings/ranking-history-series-for-an-app.md)
- [Apps that broke into the top 10 for tracked keywords](https://docs.asobeast.com/api-reference/rankings/apps-that-broke-into-the-top-10-for-tracked-keywords.md)
- [Top search results captured for a keyword](https://docs.asobeast.com/api-reference/rankings/top-search-results-captured-for-a-keyword.md)
- [Category rank history series for an app](https://docs.asobeast.com/api-reference/category-ranks/category-rank-history-series-for-an-app.md)
- [Read a top chart for one day](https://docs.asobeast.com/api-reference/charts/read-a-top-chart-for-one-day.md): One day of a free, paid or grossing chart of one store, country, category and device: every row with its position, its position on the comparison day and the movement between them, the climbers, fallers, new entries and exits, the days a capture exists for, whether this workspace follows the chart,…
- [List the chart categories of a store](https://docs.asobeast.com/api-reference/charts/list-the-chart-categories-of-a-store.md)
- [Capture a top chart today](https://docs.asobeast.com/api-reference/charts/capture-a-top-chart-today.md): Fetches today's chart from the store while you wait and stores it for every workspace, then answers the page for today. A chart already captured today is answered without a store request. Reaches the store, so it answers within the store deadline and spends one chart capture of the daily allowance o…
- [List the top charts this workspace follows](https://docs.asobeast.com/api-reference/charts/list-the-top-charts-this-workspace-follows.md)
- [Follow a top chart](https://docs.asobeast.com/api-reference/charts/follow-a-top-chart.md): Asks the daily run to capture this chart every day. The plan's follow limit counts categories, so the free, paid and grossing charts of one store, country, category and device cost one follow together. Answers 201 for a new follow and 200 with the existing one when the workspace already follows the…
- [Stop following a top chart](https://docs.asobeast.com/api-reference/charts/stop-following-a-top-chart.md)
- [Dashboard summary for an app](https://docs.asobeast.com/api-reference/analytics/dashboard-summary-for-an-app.md)
- [Visibility score history series for an app](https://docs.asobeast.com/api-reference/analytics/visibility-score-history-series-for-an-app.md)
- [Rank distribution history bands for an app](https://docs.asobeast.com/api-reference/analytics/rank-distribution-history-bands-for-an-app.md)
- [Ratings average and count history for an app](https://docs.asobeast.com/api-reference/analytics/ratings-average-and-count-history-for-an-app.md)
- [Portfolio dashboard summary for the workspace](https://docs.asobeast.com/api-reference/analytics/portfolio-dashboard-summary-for-the-workspace.md)
- [Per app signals and cross-app movers for the portfolio dashboard](https://docs.asobeast.com/api-reference/analytics/per-app-signals-and-cross-app-movers-for-the-portfolio-dashboard.md)
- [Stored reviews for an app, filtered by star, version, date and reply state](https://docs.asobeast.com/api-reference/reviews/stored-reviews-for-an-app-filtered-by-star-version-date-and-reply-state.md)
- [Complaint and praise phrases that stand out in the reviews of an app against its period](https://docs.asobeast.com/api-reference/reviews/complaint-and-praise-phrases-that-stand-out-in-the-reviews-of-an-app-against-its-period.md)
- [Ratings distribution from the latest snapshot (Google Play only)](https://docs.asobeast.com/api-reference/reviews/ratings-distribution-from-the-latest-snapshot-google-play-only.md)
- [Discard the reply kept for a review](https://docs.asobeast.com/api-reference/reviews/discard-the-reply-kept-for-a-review.md)
- [Save the reply text of a review or mark it as replied](https://docs.asobeast.com/api-reference/reviews/save-the-reply-text-of-a-review-or-mark-it-as-replied.md)
- [Draft the reply to a review with AI and keep it on the review](https://docs.asobeast.com/api-reference/reviews/draft-the-reply-to-a-review-with-ai-and-keep-it-on-the-review.md)
- [Post the kept reply of a review to its store](https://docs.asobeast.com/api-reference/reviews/post-the-kept-reply-of-a-review-to-its-store.md): Sends the saved reply text to App Store Connect or Google Play with the key connected in Integrations, records when and what was posted, and marks the review replied. Posting again after an edit replaces the reply on the store. Through a signed in session only. Answers 400 without saved text or over…
- [Withdraw the reply posted to the App Store](https://docs.asobeast.com/api-reference/reviews/withdraw-the-reply-posted-to-the-app-store.md): Deletes the response posted to App Store Connect and clears the post, keeping the reply text. Through a signed in session only. Answers 404 when nothing was posted and 409 for a Google Play review, whose API offers no removal.
- [The reply guidelines every AI draft follows](https://docs.asobeast.com/api-reference/reviews/the-reply-guidelines-every-ai-draft-follows.md)
- [Replace the reply guidelines of an app](https://docs.asobeast.com/api-reference/reviews/replace-the-reply-guidelines-of-an-app.md)
- [Translate a review with AI, or answer the translation already kept for that language](https://docs.asobeast.com/api-reference/reviews/translate-a-review-with-ai-or-answer-the-translation-already-kept-for-that-language.md)
- [ASO audit score card for an app](https://docs.asobeast.com/api-reference/audit/aso-audit-score-card-for-an-app.md)
- [ASO audit score history series for an app](https://docs.asobeast.com/api-reference/audit/aso-audit-score-history-series-for-an-app.md)
- [Run the AI audit synchronously (deprecated: use POST /apps/{id}/audit/ai/runs)](https://docs.asobeast.com/api-reference/audit/run-the-ai-audit-synchronously-deprecated:-use-post-apps-auditairuns.md)
- [Queue the AI creative analysis for an app](https://docs.asobeast.com/api-reference/audit/queue-the-ai-creative-analysis-for-an-app.md)
- [Metadata lint and keyword coverage matrix](https://docs.asobeast.com/api-reference/metadata/metadata-lint-and-keyword-coverage-matrix.md)
- [AI metadata assistant availability](https://docs.asobeast.com/api-reference/metadata/ai-metadata-assistant-availability.md)
- [Generate AI metadata drafts for an app](https://docs.asobeast.com/api-reference/metadata/generate-ai-metadata-drafts-for-an-app.md)
- [List the event markers of an app](https://docs.asobeast.com/api-reference/annotations/list-the-event-markers-of-an-app.md)
- [Mark an event on the app charts](https://docs.asobeast.com/api-reference/annotations/mark-an-event-on-the-app-charts.md): Stores a named event for one app: a label pinned to one UTC day, drawn as a vertical line on the rank history and visibility charts. market scopes the line to one storefront of the app's store and tag groups a campaign; both are optional. Writes nothing to the store.
- [Remove an event marker](https://docs.asobeast.com/api-reference/annotations/remove-an-event-marker.md)
- [List actions across every tracked app](https://docs.asobeast.com/api-reference/actions/list-actions-across-every-tracked-app.md)
- [Change the state of many actions](https://docs.asobeast.com/api-reference/actions/change-the-state-of-many-actions.md)
- [Summarize the action queue](https://docs.asobeast.com/api-reference/actions/summarize-the-action-queue.md)
- [Report AI explanation availability](https://docs.asobeast.com/api-reference/actions/report-ai-explanation-availability.md)
- [Report daily action activity](https://docs.asobeast.com/api-reference/actions/report-daily-action-activity.md)
- [Read one action](https://docs.asobeast.com/api-reference/actions/read-one-action.md)
- [Change the state of one action](https://docs.asobeast.com/api-reference/actions/change-the-state-of-one-action.md)
- [Summarize one action with the optional AI seam](https://docs.asobeast.com/api-reference/actions/summarize-one-action-with-the-optional-ai-seam.md)
- [Queue an action generation run](https://docs.asobeast.com/api-reference/actions/queue-an-action-generation-run.md)
- [List actions for one tracked app](https://docs.asobeast.com/api-reference/actions/list-actions-for-one-tracked-app.md)
- [Keyword gap and positioning analysis](https://docs.asobeast.com/api-reference/competitors/keyword-gap-and-positioning-analysis.md)
- [Untracked apps recurring in your keyword results](https://docs.asobeast.com/api-reference/competitors/untracked-apps-recurring-in-your-keyword-results.md)
- [Suggest competitors from the keyword results and similar apps](https://docs.asobeast.com/api-reference/competitors/suggest-competitors-from-the-keyword-results-and-similar-apps.md): The untracked apps that recur in this app's own keyword results over the last 30 days, with how often and how high they rank, followed by the apps the store lists as similar, each with its icon, minus the app and its tracked competitors, at most ten. On Google Play a similar app is kept only when it…
- [List competitors for an app](https://docs.asobeast.com/api-reference/competitors/list-competitors-for-an-app.md)
- [Add a competitor app from a store URL](https://docs.asobeast.com/api-reference/competitors/add-a-competitor-app-from-a-store-url.md)
- [Remove a competitor from an app](https://docs.asobeast.com/api-reference/competitors/remove-a-competitor-from-an-app.md)
- [The asobeast MCP server](https://docs.asobeast.com/mcp/introduction.md): asobeast ships a Model Context Protocol surface that reads by default and changes things only for a token you allow. Connect to the hosted endpoint or run the stdio server yourself, both with the same tools.
- [Connect an agent](https://docs.asobeast.com/mcp/setup.md): Connect straight to the hosted endpoint, or run the stdio server yourself. Both transports expose the same tools, and the scope of your token decides whether they include the tools that make changes.
- [MCP tool reference](https://docs.asobeast.com/mcp/tools.md): 37 read only tools covering apps, keywords, competitors, top charts, annotations, rankings, SERPs, audits, reviews, analytics and the Action Center, plus 7 opt in tools that change keywords, competitors, actions and annotations.
- [MCP recipes](https://docs.asobeast.com/mcp/recipes.md): Nine prompts that work well against the asobeast MCP server, each with the tools it exercises, from a weekly review to tracking keywords and closing actions.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.