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

- Every request costs 1 credit, plus the price of each datapoint actually returned.
- Historical endpoints: the datapoint's base price for the first available day, then
  10% of it per additional day. **One range call is far cheaper than N single-day calls.**
  A 10-credit datapoint over 30 days costs 39, not 300.
- Downloads and revenues are the expensive ones: 500 base, 50 per extra day. A 45-day
  downloads request for one app is 2,701 credits. Category metrics and conversion
  benchmarks are 1,000 base.
- Batch. Most endpoints take several apps or keywords per call and you pay 1 credit per
  request regardless.
- Smoke-test new calls with `limit=1`, then read `metadata.request.cost` before scaling.
- Every response carries `cost` (what was charged) and `max_credit_cost` (the pre-flight
  worst case). 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 1,000 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.