# AppGoat Docs

> App Store and Google Play data for your code and your agents: REST API, MCP server and playbooks.

- [Quickstart](https://docs.appgoat.ai/index.md): App Store and Google Play data for your code and your agents. One API key, one header, the same data over REST and MCP.
- [App identifiers](https://docs.appgoat.ai/concepts/app-resolver.md): Every app-scoped endpoint takes one {app} path segment that accepts anything that identifies an app.
- [Freshness](https://docs.appgoat.ai/concepts/freshness.md): App-scoped reads refresh data from the store when ours is older than max_age, and tell you how old it is in meta.freshness.
- [Response envelope](https://docs.appgoat.ai/concepts/envelope.md): Every success is { data, meta }: data is an object or a list, meta carries what the call cost and how fresh the answer is.
- [Credits](https://docs.appgoat.ai/concepts/credits.md): Plans come with monthly credits; every call reports its cost. Failed requests are free.
- [Pagination and fields](https://docs.appgoat.ai/concepts/pagination.md): Cursor pagination with limit and cursor, optional sections with include=, and smaller responses with fields=.
- [Rate limits](https://docs.appgoat.ai/concepts/rate-limits.md): Requests per second are per organization and depend on your plan.
- [Webhooks](https://docs.appgoat.ai/webhooks.md): Get events from your watches pushed to a URL, a Slack channel or a GitHub repository as they happen.
- [Connections](https://docs.appgoat.ai/connections.md): Connect App Store Connect, Google Play Console or Apple Ads so agents can read your own reviews, listings and campaigns and propose changes.
- [Error codes](https://docs.appgoat.ai/errors/list.md): Every AppGoat API error code with its HTTP status, cause and fix.
- [invalid_param](https://docs.appgoat.ai/errors/invalid_param.md): 400 · A parameter is missing or invalid
- [invalid_api_key](https://docs.appgoat.ai/errors/invalid_api_key.md): 401 · Missing or invalid API key
- [unauthorized](https://docs.appgoat.ai/errors/unauthorized.md): 401 · Not authorized
- [insufficient_credits](https://docs.appgoat.ai/errors/insufficient_credits.md): 402 · Not enough credits
- [plan_limit](https://docs.appgoat.ai/errors/plan_limit.md): 402 · Not included in your plan
- [free_audit_used](https://docs.appgoat.ai/errors/free_audit_used.md): 402 · Free App Audit already used
- [forbidden](https://docs.appgoat.ai/errors/forbidden.md): 403 · Needs approval by a person
- [not_found](https://docs.appgoat.ai/errors/not_found.md): 404 · Not found
- [app_not_found](https://docs.appgoat.ai/errors/app_not_found.md): 404 · App not found
- [developer_not_found](https://docs.appgoat.ai/errors/developer_not_found.md): 404 · Developer not found
- [job_not_found](https://docs.appgoat.ai/errors/job_not_found.md): 404 · Job not found
- [method_not_allowed](https://docs.appgoat.ai/errors/method_not_allowed.md): 405 · Method not allowed
- [conflict](https://docs.appgoat.ai/errors/conflict.md): 409 · Conflict
- [not_ready](https://docs.appgoat.ai/errors/not_ready.md): 4xx · Not ready yet
- [invalid_credentials](https://docs.appgoat.ai/errors/invalid_credentials.md): 422 · Connection credentials rejected
- [rate_limited](https://docs.appgoat.ai/errors/rate_limited.md): 429 · Too many requests
- [internal_error](https://docs.appgoat.ai/errors/internal_error.md): 500 · Internal error
- [upstream_unavailable](https://docs.appgoat.ai/errors/upstream_unavailable.md): 502 · Data service unavailable
- [provider_error](https://docs.appgoat.ai/errors/provider_error.md): 502 · Store API error
- [not_configured](https://docs.appgoat.ai/errors/not_configured.md): 503 · Not configured
- [MCP server setup](https://docs.appgoat.ai/mcp-server/setup.md): Add AppGoat to Claude or Cursor in one click, to Claude Code with one command, or to any MCP client.
- [Tools](https://docs.appgoat.ai/mcp-server/tools.md): The tools of the AppGoat MCP server, what they do and what they cost.
- [Playbooks as prompts](https://docs.appgoat.ai/mcp-server/playbooks.md): The AppGoat playbooks are bundled with the MCP server as prompts, so clients that show prompts can run them as slash commands.
- [API reference](https://docs.appgoat.ai/api-reference/introduction.md): AppGoat REST API: apps, reviews, metric history, listing changes, keywords, competitors, search, top charts, developers, audits, watches, webhooks, connections, actions and jobs.
- [Get app](https://docs.appgoat.ai/api-reference/endpoint/get-app.md): Use this first when a user mentions an app. Pass any identifier or a name in `{app}`. Data older than `max_age` (default 7 days) is refreshed from the store; an app we never saw is fetched on the spot (if it is still being fetched after ~25 s you get HTTP 202 with `data: null` and a `job_id`). `incl…
- [List reviews](https://docs.appgoat.ai/api-reference/endpoint/list-reviews.md): Up to 100 reviews per page (1 credit per page). Combine `rating=1-2` with `since` to find recent complaints, `q` for full-text search, `version` to see what users say about a release. The latest US reviews are refreshed when older than `max_age` (default 1 day). AI tags (`sentiment`, `intent`, `seve…
- [Get app history](https://docs.appgoat.ai/api-reference/endpoint/get-app-history.md): One row per country and day **on which a value changed** — carry the previous row forward for the days in between. Defaults to the last 90 days. Use it to chart growth or spot rating drops.
- [List app changes](https://docs.appgoat.ai/api-reference/endpoint/list-app-changes.md): Typed change feed, newest first: one entry per changed field with `old` and `new` values. Fields include version, release_notes, title, subtitle, description, screenshots, icon, price, iap, iap_range, privacy, in_app_events, badges, featured, editors_choice, installs, content_rating, developer. Idea…
- [List app keywords](https://docs.appgoat.ai/api-reference/endpoint/list-app-keywords.md): From the latest ranking we hold for each term: our keyword universe (re-ranked weekly, top 50) plus your own tracked keywords (`source: tracked`). Use it for ASO audits and to find keyword gaps against a competitor (call it for both apps and compare).
- [List competitors](https://docs.appgoat.ai/api-reference/endpoint/list-competitors.md): Scored list: `shared_keywords` (search terms both apps rank for) counts most, the store's own similar-apps list (`similar_position`) adds a boost. Feed the result into `getApp` / `listAppChanges` for a competitor digest.
- [Get app insights](https://docs.appgoat.ai/api-reference/endpoint/get-app-insights.md): Built from the AI tags on every review (sentiment, intent, severity, topic). `top_issues` are topics carried by negative / bug / crash / UX / pricing reviews, with `last_30d` vs `prev_30d` counts and sample reviews; `versions` shows what each release changed in sentiment and topics; `sentiment_over_…
- [Search apps](https://docs.appgoat.ai/api-reference/endpoint/search-apps.md): Exact title matches first, then prefix, then substring; most ratings first within each group.
- [Get chart](https://docs.appgoat.ai/api-reference/endpoint/get-chart.md): Entries carry `delta` (positions gained since the previous changed capture; negative = dropped) and `is_new`; `dropped` lists apps that fell out. Charts are captured daily for every country × category.
- [Get keywords](https://docs.appgoat.ai/api-reference/endpoint/get-keywords.md): `popularity` is 5–100 (search volume proxy; `popularity_source: apple` = Apple Search Ads data), `difficulty` 0–100 (how entrenched the top 10 is), `est_downloads_at_1` the modelled daily downloads of the #1 result. Terms not measured in the last 7 days are measured live (≤ 5 per call, 2–5 s each) w…
- [List tracked keywords](https://docs.appgoat.ai/api-reference/endpoint/list-tracked-keywords.md)
- [Track keywords](https://docs.appgoat.ai/api-reference/endpoint/track-keywords.md): Each (term × store × country) uses one keyword slot of your plan; a request that would exceed it tracks nothing and returns 402 plan_limit.
- [Get tracked keyword](https://docs.appgoat.ai/api-reference/endpoint/get-tracked-keyword.md)
- [Update tracked keyword](https://docs.appgoat.ai/api-reference/endpoint/update-tracked-keyword.md)
- [Untrack keyword](https://docs.appgoat.ai/api-reference/endpoint/untrack-keyword.md)
- [Get tracked keyword ranks](https://docs.appgoat.ai/api-reference/endpoint/get-tracked-keyword-ranks.md)
- [Run tracked keyword](https://docs.appgoat.ai/api-reference/endpoint/run-tracked-keyword.md): If it was ranked within the last hour you get that ranking back (200, `queued:false`, free) instead.
- [Get developer](https://docs.appgoat.ai/api-reference/endpoint/get-developer.md): Name, store page, website and domain, country, app count, total ratings and installs, top category, their apps (most ratings first) and the linked developer in the other store.
- [Run App Audit](https://docs.appgoat.ai/api-reference/endpoint/run-app-audit.md): Refreshes the listing, tags recent reviews, probes ~20 search terms (popularity, difficulty, the app's rank, relevance), compares competitors, then writes a prioritised report: `report.actions` (what to do first, with the evidence and a playbook), `report.metadata` (title / subtitle / keyword-field…
- [List audits](https://docs.appgoat.ai/api-reference/endpoint/list-audits.md)
- [Get audit](https://docs.appgoat.ai/api-reference/endpoint/get-audit.md): `status`: queued, running, batched (narrative queued in the batch API), done or failed. `include=facts` adds the measured facts the report is built from.
- [Update audit](https://docs.appgoat.ai/api-reference/endpoint/update-audit.md): `white_label: true` re-applies your current branding (use it after changing the branding), `false` shows the standard AppGoat report. 402 plan_limit for white_label on plans without white-label audits.
- [List watches](https://docs.appgoat.ai/api-reference/endpoint/list-watches.md): `meta.usage` has watched apps and keyword slots used vs your plan (`null` limit = unlimited).
- [Create watch](https://docs.appgoat.ai/api-reference/endpoint/create-watch.md): Use this when the user wants to be told about changes ("tell me when a competitor updates", "alert me when my rating drops", "track my ranks for these keywords"). Kinds: - `app` { app }: new versions, metadata / price changes, featuring, rating drops, review and ratings spikes,   chart entries for t…
- [Get watch](https://docs.appgoat.ai/api-reference/endpoint/get-watch.md)
- [Update watch](https://docs.appgoat.ai/api-reference/endpoint/update-watch.md): Send only what changes; `settings` is merged into the current settings. Growing a watch re-checks your plan's limits (402 plan_limit).
- [Delete watch](https://docs.appgoat.ai/api-reference/endpoint/delete-watch.md)
- [List events](https://docs.appgoat.ai/api-reference/endpoint/list-events.md): Each event has a deterministic one-line `title`, an AI `summary` (or null), a `significance` (0–1) and a typed `payload`. Only changes that reach the watch's `settings.significance` become events. To poll, pass `since=` the `created_at` of the newest event you already handled (or remember its id and…
- [List webhooks](https://docs.appgoat.ai/api-reference/endpoint/list-webhooks.md)
- [Create webhook](https://docs.appgoat.ai/api-reference/endpoint/create-webhook.md): `kind`: - `webhook` (default): POST of the event JSON, signed with `appgoat-signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`.   The `secret` is returned once, here (rotate with PATCH rotate_secret). Answer 2xx within 10 s. - `slack`: `url` is a Slack incoming webhook (https://hook…
- [Get webhook](https://docs.appgoat.ai/api-reference/endpoint/get-webhook.md)
- [Update webhook](https://docs.appgoat.ai/api-reference/endpoint/update-webhook.md)
- [Delete webhook](https://docs.appgoat.ai/api-reference/endpoint/delete-webhook.md)
- [Test webhook](https://docs.appgoat.ai/api-reference/endpoint/test-webhook.md)
- [List webhook deliveries](https://docs.appgoat.ai/api-reference/endpoint/list-webhook-deliveries.md)
- [List connections](https://docs.appgoat.ai/api-reference/endpoint/list-connections.md): Use the connection `id` in `POST /v1/actions` (or omit it when only one connection fits). `status: invalid` means the provider rejected the credentials since they were added (`last_error` says why); fix them and call `POST /v1/connections/{id}/verify`. `mode: read_only` connections can dry-run actio…
- [Create connection](https://docs.appgoat.ai/api-reference/endpoint/create-connection.md): Credentials per provider (all are verified with one cheap read before anything is stored; they are encrypted with AES-256-GCM and never returned): - `asc`: `{ issuer_id, key_id, private_key, vendor_number? }` from App Store Connect → Users and Access →   Integrations → App Store Connect API (role Ap…
- [Get connection](https://docs.appgoat.ai/api-reference/endpoint/get-connection.md)
- [Update connection](https://docs.appgoat.ai/api-reference/endpoint/update-connection.md)
- [Delete connection](https://docs.appgoat.ai/api-reference/endpoint/delete-connection.md)
- [Verify connection](https://docs.appgoat.ai/api-reference/endpoint/verify-connection.md)
- [List connection reviews](https://docs.appgoat.ai/api-reference/endpoint/list-connection-reviews.md): `unanswered=true` keeps reviews without a developer reply (the "reply to every review" playbook). Play only returns reviews written or edited in the last 7 days (Google API limit); App Store Connect returns all.
- [Get connection listing](https://docs.appgoat.ai/api-reference/endpoint/get-connection-listing.md): App Store name/subtitle/description/keywords/what's new need a version in Prepare for Submission; promotional text is editable on the live version. Play fields are always editable.
- [Get connection ads](https://docs.appgoat.ai/api-reference/endpoint/get-connection-ads.md): `view=campaigns` → `ad_groups` (campaign_id) → `keywords` (campaign_id, ad_group_id) gives the ids the ads.* actions take. `view=report&level=keywords|searchterms|adgroups|campaigns&campaign_id=` returns impressions, taps, installs, spend, avg CPT / CPA for `start`..`end` (default the last 7 days, U…
- [List actions](https://docs.appgoat.ai/api-reference/endpoint/list-actions.md)
- [Create action](https://docs.appgoat.ai/api-reference/endpoint/create-action.md): Computes the before → after `diff` from the live account and runs guardrails (policy / tone / claims probabilities for text, plus deterministic checks like character limits and bid jumps). Free. - `dry_run: true` → a `draft` (24 h) with the diff: show it to the user. To go ahead, call   `POST /v1/ac…
- [Get action](https://docs.appgoat.ai/api-reference/endpoint/get-action.md)
- [Approve action](https://docs.appgoat.ai/api-reference/endpoint/approve-action.md): From an API key / agent: a `draft` becomes `pending_approval` (a person approves at `approve_url`) unless an auto-apply rule clears it, in which case it is applied. A `pending_approval` action needs a person unless the org enabled agent approval (403 otherwise). From the dashboard: applies it. The d…
- [Reject action](https://docs.appgoat.ai/api-reference/endpoint/reject-action.md)
- [Get job](https://docs.appgoat.ai/api-reference/endpoint/get-job.md): Poll every few seconds until `status` is done / partial / failed, then repeat the original call.
- [Get OpenAPI](https://docs.appgoat.ai/api-reference/endpoint/get-openapi.md)
- [Get me](https://docs.appgoat.ai/api-reference/endpoint/get-me.md)

## OpenAPI Specs

- [openapi](/openapi.json)

## Optional

- [Playbooks](https://appgoat.ai/playbooks)
- [Pricing](https://appgoat.ai/pricing)


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