# asobeast

> asobeast is a self hosted App Store Optimization toolkit. Point it at an App Store or Google Play URL and it tracks that listing's keywords, rankings, competitors, reviews and metadata on hardware you control.

## Docs

- [Change the state of one action](https://docs.asobeast.com/api-reference/actions/change-the-state-of-one-action.md)
- [List actions across every tracked app](https://docs.asobeast.com/api-reference/actions/list-actions-across-every-tracked-app.md)
- [List actions for one tracked app](https://docs.asobeast.com/api-reference/actions/list-actions-for-one-tracked-app.md)
- [Queue an action generation run](https://docs.asobeast.com/api-reference/actions/queue-an-action-generation-run.md)
- [Report AI explanation availability](https://docs.asobeast.com/api-reference/actions/report-ai-explanation-availability.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)
- [Summarize the action queue](https://docs.asobeast.com/api-reference/actions/summarize-the-action-queue.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)
- [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)
- [Dashboard summary for an app](https://docs.asobeast.com/api-reference/analytics/dashboard-summary-for-an-app.md)
- [Portfolio dashboard summary for the workspace](https://docs.asobeast.com/api-reference/analytics/portfolio-dashboard-summary-for-the-workspace.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)
- [Visibility score history series for an app](https://docs.asobeast.com/api-reference/analytics/visibility-score-history-series-for-an-app.md)
- [Delete an app](https://docs.asobeast.com/api-reference/apps/delete-an-app.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)
- [Import an app from a store URL](https://docs.asobeast.com/api-reference/apps/import-an-app-from-a-store-url.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)
- [List imported apps](https://docs.asobeast.com/api-reference/apps/list-imported-apps.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)
- [Unlink an app from its group](https://docs.asobeast.com/api-reference/apps/unlink-an-app-from-its-group.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 for an app and recompute](https://docs.asobeast.com/api-reference/audit/run-the-ai-audit-for-an-app-and-recompute.md)
- [Change password and reset other sessions](https://docs.asobeast.com/api-reference/auth/change-password-and-reset-other-sessions.md)
- [Create a personal api token](https://docs.asobeast.com/api-reference/auth/create-a-personal-api-token.md)
- [Current authenticated user](https://docs.asobeast.com/api-reference/auth/current-authenticated-user.md)
- [List personal api tokens](https://docs.asobeast.com/api-reference/auth/list-personal-api-tokens.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)
- [Public auth configuration and session state](https://docs.asobeast.com/api-reference/auth/public-auth-configuration-and-session-state.md)
- [Register an account](https://docs.asobeast.com/api-reference/auth/register-an-account.md)
- [Revoke a personal api token](https://docs.asobeast.com/api-reference/auth/revoke-a-personal-api-token.md)
- [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 Settings, where it is shown once and prefixed with asob_.
- [Category rank history series for an app](https://docs.asobeast.com/api-reference/category-ranks/category-rank-history-series-for-an-app.md)
- [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)
- [Recent metadata changes across the workspace](https://docs.asobeast.com/api-reference/changes/recent-metadata-changes-across-the-workspace.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)
- [Keyword gap and positioning analysis](https://docs.asobeast.com/api-reference/competitors/keyword-gap-and-positioning-analysis.md)
- [List competitors for an app](https://docs.asobeast.com/api-reference/competitors/list-competitors-for-an-app.md)
- [Remove a competitor from an app](https://docs.asobeast.com/api-reference/competitors/remove-a-competitor-from-an-app.md)
- [Untracked apps recurring in your keyword results](https://docs.asobeast.com/api-reference/competitors/untracked-apps-recurring-in-your-keyword-results.md)
- [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.
- [Delete an email alert](https://docs.asobeast.com/api-reference/email-alerts/delete-an-email-alert.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)
- [Send a sample email to an alert recipient](https://docs.asobeast.com/api-reference/email-alerts/send-a-sample-email-to-an-alert-recipient.md)
- [Update an email alert](https://docs.asobeast.com/api-reference/email-alerts/update-an-email-alert.md)
- [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.
- [Liveness, database and pipeline health check](https://docs.asobeast.com/api-reference/health/liveness-database-and-pipeline-health-check.md)
- [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.
- [Estimate the daily store request budget](https://docs.asobeast.com/api-reference/jobs/estimate-the-daily-store-request-budget.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)
- [Add manual keywords](https://docs.asobeast.com/api-reference/keywords/add-manual-keywords.md)
- [Aggregate suggest spider probes for a term](https://docs.asobeast.com/api-reference/keywords/aggregate-suggest-spider-probes-for-a-term.md)
- [Compare keyword positions against competitors](https://docs.asobeast.com/api-reference/keywords/compare-keyword-positions-against-competitors.md)
- [Enqueue suggest spider probes for a term](https://docs.asobeast.com/api-reference/keywords/enqueue-suggest-spider-probes-for-a-term.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)
- [List tracked keywords for an app](https://docs.asobeast.com/api-reference/keywords/list-tracked-keywords-for-an-app.md)
- [Set the manual iOS keyword field](https://docs.asobeast.com/api-reference/keywords/set-the-manual-ios-keyword-field.md)
- [Stop tracking a keyword](https://docs.asobeast.com/api-reference/keywords/stop-tracking-a-keyword.md)
- [Suggest keywords via metadata, search or similar](https://docs.asobeast.com/api-reference/keywords/suggest-keywords-via-metadata-search-or-similar.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)
- [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)
- [Metadata lint and keyword coverage matrix](https://docs.asobeast.com/api-reference/metadata/metadata-lint-and-keyword-coverage-matrix.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)
- [Ranking history series for an app](https://docs.asobeast.com/api-reference/rankings/ranking-history-series-for-an-app.md)
- [Top search results captured for a keyword](https://docs.asobeast.com/api-reference/rankings/top-search-results-captured-for-a-keyword.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)
- [Stored reviews for an app, filtered by star and version](https://docs.asobeast.com/api-reference/reviews/stored-reviews-for-an-app-filtered-by-star-and-version.md)
- [Enqueue an on demand keyword score](https://docs.asobeast.com/api-reference/scoring/enqueue-an-on-demand-keyword-score.md)
- [Delete an alert webhook](https://docs.asobeast.com/api-reference/webhooks/delete-an-alert-webhook.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)
- [Send a sample payload to a webhook](https://docs.asobeast.com/api-reference/webhooks/send-a-sample-payload-to-a-webhook.md)
- [Update an alert webhook](https://docs.asobeast.com/api-reference/webhooks/update-an-alert-webhook.md)
- [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.
- [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.
- [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, and one search serves the app and every competitor at once.
- [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.
- [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.
- [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.
- [Traffic, difficulty and opportunity](https://docs.asobeast.com/concepts/scoring.md): Traffic and difficulty are 0 to 100 scores persisted with their evidence. Opportunity is computed per app on read and is never stored anywhere.
- [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.
- [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 at runtime and proxies browser traffic to it, so one image can target any API without a rebuild.
- [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.
- [Work the Action Center](https://docs.asobeast.com/guides/action-center.md): Eight deterministic rules run over your stored history and return a prioritized queue, each recommendation carrying the exact numbers behind it.
- [Enable the optional AI features](https://docs.asobeast.com/guides/ai-features.md): Set OPENAI_API_KEY to enable AI audit evidence, metadata drafts and action explanations. Every other feature works with the key left unset.
- [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.
- [Run an ASO audit](https://docs.asobeast.com/guides/aso-audit.md): The audit scores ten weighted factors from stored data and your answers. Subtitle and keyword field carry weight 0 for a Google Play app.
- [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.
- [Track competitors](https://docs.asobeast.com/guides/competitors.md): Add a competitor from a store URL or from a stored SERP snapshot. Competitors cost no extra store requests on keywords you already track.
- [Export data](https://docs.asobeast.com/guides/export-data.md): The keyword monitor and the rankings view both export CSV. Keyword exports carry the score provenance columns alongside every number.
- [Import an app](https://docs.asobeast.com/guides/import-an-app.md): Paste an App Store or Google Play URL and asobeast captures the first snapshot, extracts keywords and tracks them in the home storefront.
- [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.
- [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 pasted private iOS keyword field.
- [Compare a portfolio](https://docs.asobeast.com/guides/portfolio.md): Link the App Store and Google Play listings of one product into a group, compare visibility across it and receive a weekly portfolio digest.
- [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.
- [Sync reviews and mine keyword ideas](https://docs.asobeast.com/guides/reviews.md): Reviews sync in the daily pipeline for the home storefront. Repeated language in negative reviews becomes keyword ideas and action items.
- [Track keywords](https://docs.asobeast.com/guides/track-keywords.md): Add keywords per storefront on the keyword monitor, paste the private iOS keyword field by hand, and watch the request budget that every added market draws on.
- [asobeast documentation](https://docs.asobeast.com/index.md): asobeast is an open source, self hosted App Store Optimization toolkit. It tracks an App Store or Google Play listing on hardware you control.
- [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.
- [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.
- [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. Releases before 1.0.0 have no latest tag.
- [System requirements](https://docs.asobeast.com/install/requirements.md): asobeast needs Docker with Compose, roughly 2 GB of memory and an outbound internet connection. PostgreSQL 18 and Redis 8 ship with the stack.
- [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.
- [The asobeast MCP server](https://docs.asobeast.com/mcp/introduction.md): asobeast ships a read only Model Context Protocol server. It runs locally over stdio, authenticates with a personal API token and exposes 21 tools.
- [MCP recipes](https://docs.asobeast.com/mcp/recipes.md): Six prompts that work well against the asobeast MCP server, each with the tools it exercises, from a weekly review to a metadata draft.
- [Connect an agent](https://docs.asobeast.com/mcp/setup.md): Set ASOBEAST_API_URL and ASOBEAST_API_TOKEN, then register the built entrypoint with your MCP client using an absolute path to the file.
- [MCP tool reference](https://docs.asobeast.com/mcp/tools.md): Twenty one read only tools covering apps, keywords, rankings, SERPs, audits, reviews, analytics, the request budget and the Action Center queue.
- [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.
- [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.
- [Recover a wedged release](https://docs.asobeast.com/operations/release-recovery.md): Release Please advanced the version manifest without creating the tag, so every later run reported success while publishing nothing. Recognize it, then finish the release by hand.
- [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.
- [Troubleshooting](https://docs.asobeast.com/operations/troubleshooting.md): Fifteen 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.
- [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.
- [The queue dashboard and the OpenAPI surface](https://docs.asobeast.com/security/admin-surfaces.md): The queue dashboard and the OpenAPI routes answer 404 to anyone who is not a signed in owner, because the surface does not confirm it exists.
- [Personal API tokens](https://docs.asobeast.com/security/api-tokens.md): Mint a revocable personal API token in Settings and send it as a bearer header. The plaintext value is shown once and stored only as a hash.
- [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.
- [Hosting behind TLS and a reverse proxy](https://docs.asobeast.com/security/hosting.md): Set AUTH_COOKIE_SECURE to true on any deployment reachable over TLS, and set TRUST_PROXY only when your reverse proxy controls X-Forwarded-For.
- [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.

## OpenAPI Specs

- [openapi](https://docs.asobeast.com/api-reference/openapi.json)