Agent context files

If you work with an agent in a repo, the fastest way to get good results from the AppTweak API is to put the context in the repo rather than re-explaining it every session.

Two mechanisms, and you can use both:

start-here-guide — an MCP tool that returns the current spec map and gotcha list. Always up to date, costs nothing, but only your agent can read it. Have it called at the start of every session.
A context file in your project — persists across sessions, survives context compaction, and you can read and edit it yourself. That's what this page gives you.

Drop this in your project

Save it as AGENTS.md at your repo root, or under whatever filename your tool expects — CLAUDE.md for Claude Code, a rule file for Cursor. Trim the sections you don't need.

# AppTweak API — context for agents

## Connection

MCP server: `https://developers.apptweak.com/mcp`
Auth: `x-apptweak-key` header. Key lives at https://app.apptweak.com/apt-api
Rate limit: 60 requests / 10 seconds.

Call `start-here-guide` first in every session — it carries the current gotcha list,
which may be ahead of this file.

## Which spec

Three OpenAPI specs are indexed. Pass the exact title to `get-endpoint` / `list-endpoints`.

- `apptweak-store-api` — the main ASO dataset: app metadata and metrics, category and
  keyword rankings, reviews, keyword metrics, top charts, paid keyword bids.
- `apptweak-integrations-api` — data from accounts the customer has connected
  (App Store Connect, Google Play Console). Requires the connection to already exist.
- `apptweak-api` — utilities: credit balance and usage, valid countries and languages,
  DNA reference data, tracked-applications CRUD.

## Free vs. paid

Documentation tools (`list-specs`, `list-endpoints`, `search-endpoints`, `get-endpoint`,
`search`, `fetch`, `start-here-guide`, `app-id-lookup`, the `*-guide` tools) cost
nothing and need no API key.

`execute-request` is the only tool that calls the API, the only one that needs the key,
and the only one that spends credits.

Design the whole integration from documentation before executing anything.

## Cost rules — read before executing

- Current data: 1 credit per app per metric. History: 5 per app per metric, for any date range up to one full calendar year.
- Downloads and revenues are estimates: 10 credits per app and metric (current), 50 (history). Estimates require an API plan with estimates access.
- Live search: 10 credits; live search history: 5; review search: 10; console data: 1 per request; account and reference endpoints: free.
- Errors are free, except AppNotAvailableError (1 credit).
- Batch apps and keywords within the endpoint’s limits. The cost follows the endpoint’s documented price.
- Every response carries `cost`. It does **not** carry remaining balance — for that, call the usage/credits endpoint on `apptweak-api`. **That call is free**, so check the balance at the start of any heavy session and between large batches.
- Tell me before any single call over 100 credits.

## Gotchas — these produce wrong answers, not errors


1. **`country` / `language` are free text, not enums**, and store endpoints link to    a static docs page rather than the live list. If a code is rejected, call the
   `countries` and `languages` endpoints on `apptweak-api` instead of guessing.
2. **iOS and Android integration reports are not symmetrical.** iOS reports break   down by
   device and in-app event only. There is no iOS equivalent of the Android
   channel / traffic-source breakdown. Don't assume parity.
3. **A 200 with empty data from `apptweak-integrations-api`** usually means the customer's
   App Store Connect or Play Console account isn't connected — not a bug, and not
   "no data exists".

## Endpoint quirks worth knowing

- Keyword rankings history accepts **max 5 keywords per call**. Batch accordingly.
- Top charts: iOS uses numeric category IDs, Android uses category names. Call
  `get-endpoint` for the lists.
- Reviews split across three endpoints — search by keyword or rating
  (`/apps/reviews/search.json`, supports `term` and `replied`), ratings distribution over
  time (`/apps/reviews/stats.json`), and what's currently on the store page
  (`/apps/reviews/top-displayed.json`). To find complaints, run several `term` searches
  ("crash", "bug", "price", "cancel") rather than one broad pull.
- Don't know an app's store ID? Use `app-id-lookup` — it takes a name or store URL and
  costs nothing.
- Google Play Console installs per keyword with a branded / generic / competitor
  breakdown: use `gpc-keyword-installs-guide`, don't assemble it from raw endpoints.

## Preferred workflow

For anything that runs more than once: use the MCP to find the endpoints and confirm the response shape, then write code that calls the API directly. Don't route bulk data through the conversation.

`llms.txt`

We publish developers.apptweak.com/llms.txt — an index of every documentation page with a one-line description, in the llms.txt format. Agents that support it can use it to navigate the docs without the MCP at all. Useful when you want documentation context in a tool that isn't MCP-capable.

Recipes

Recipes are ready-made Python and Ruby scripts for concrete use cases. They're a good starting point to hand an agent: "adapt this recipe to do X" produces better results than "write this from scratch", and the recipe already encodes the right endpoint choices.

Keeping it current

The gotcha list changes as we fix things. start-here-guide is the live version; the snippet above is a snapshot. If your agent reports something that contradicts this file, trust the tool and update your copy.