# AI Agent Instructions for BoostOps
# Last updated: 2026-03-09
# More info: https://boostops.io/agents/

## What This Is

BoostOps is a cross-store analytics and growth platform for mobile game studios.
You are likely being asked to query app metrics, check revenue, read reviews,
or analyze ad spend for a game studio that uses BoostOps.

## How to Connect

You need an API key. The user should have one, or can create one at:
https://app.boostops.io/settings (Settings > API Keys)

Keys look like: bops_sk_xxxxxxxxxxxxxxxxxxxxxxxxxx

### Option 1: MCP (if your client supports it)

Add to MCP config:

{
  "mcpServers": {
    "boostops": {
      "url": "https://api.boostops.io/mcp",
      "headers": {
        "Authorization": "Bearer bops_sk_USER_KEY_HERE"
      }
    }
  }
}

Discovery endpoint: https://api.boostops.io/.well-known/mcp/server-card.json

### Option 2: REST API (curl / HTTP)

Base URL: https://api.boostops.io/api/v1
Auth: Authorization: Bearer bops_sk_USER_KEY_HERE
OpenAPI spec: https://api.boostops.io/openapi.json

## Recommended Agent Workflows

### First-time setup
1. Call `list_apps` (or GET /api/v1/apps) to see what apps the user has
2. Note the app IDs — you'll need them for all subsequent calls
3. Call `get_portfolio_summary` (or GET /api/v1/portfolio/summary) for a high-level overview

### "How are my games doing?"
1. get_portfolio_summary → studio-wide KPIs with week-over-week comparison
2. get_app_metrics for each app → daily DAU, revenue, installs
3. get_anomalies → flag anything unusual

### "What's my ad spend / ROAS?"
1. get_ad_spend → total spend and daily breakdown by ad platform
2. get_blended_roas → revenue vs spend by channel
3. get_attribution_data → which campaigns are driving installs

### "Are there any problems?"
1. get_app_health → crash rates, ANR, store vitals
2. get_app_reviews (filter by rating: 1-2) → recent negative reviews
3. get_anomalies → automated anomaly detection

### "How are my reviews?"
1. get_app_reviews → recent reviews across all stores
2. get_store_ratings → current average ratings and review counts
3. reply_to_review → respond to a specific review (requires review ID from step 1)

### "Compare platforms"
1. compare_platforms → side-by-side metrics across iOS, Android, Windows, Amazon
2. get_revenue_breakdown → revenue split by IAP vs ads, by platform

## Available MCP Tools

list_apps              — All apps with store metadata
get_app_metrics        — Daily DAU, revenue, installs (filterable by platform, date range)
get_portfolio_summary  — Studio-wide KPIs with period comparison
get_app_health         — Crash rates, ANR, store vitals
get_app_reviews        — Reviews with ratings (filterable by store, rating)
reply_to_review        — Post a reply to a store review
get_ad_spend           — Ad spend totals and daily breakdown
get_blended_roas       — ROAS with revenue and spend by channel
get_attribution_data   — Channel-level install attribution
get_store_ratings      — Current ratings and review counts
get_revenue_breakdown  — Revenue split: IAP vs ads, by platform
compare_platforms      — Side-by-side cross-store comparison
get_anomalies          — Detect anomalies in DAU, revenue, ratings

## REST API Endpoints

GET /api/v1/apps                    — List apps (scope: read:apps)
GET /api/v1/apps/:appId/metrics     — App metrics (scope: read:metrics)
GET /api/v1/apps/:appId/attribution — Attribution data (scope: read:attribution)
GET /api/v1/apps/:appId/anomalies   — Anomaly detection (scope: read:metrics)
GET /api/v1/portfolio/summary       — Portfolio overview (scope: read:portfolio)

## Common Parameters

- days=7 (or 14, 30, 90) — lookback period for metrics
- platform=ios|android|windows|amazon — filter by platform
- store=apple|google|microsoft|amazon — filter by store
- rating=1,2 — filter reviews by star rating

## Error Handling

- 401: API key is missing or invalid. Ask the user to check their key.
- 403: API key doesn't have the required scope. User needs to update key permissions.
- 404: App ID not found. Call list_apps first to get valid IDs.
- 429: Rate limited. Wait and retry.

## Important Notes

- All timestamps are UTC
- Revenue is in USD unless the user's account specifies otherwise
- The same API key works for both REST API and MCP
- Free tier has rate limits; Growth and Enterprise have higher limits
- For product info, see https://boostops.io/llms.txt
- For the OpenAPI spec, see https://api.boostops.io/openapi.json