# AI Agent Instructions for BoostOps
# Last updated: 2026-03-11
# 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

### OpenAPI Specification (recommended)

Full OpenAPI 3.1 spec for auto-discovery:

- Spec URL: https://app.boostops.io/openapi.json
- Base URL: https://api.boostops.io/api/v1
- Auth: Authorization: Bearer bops_sk_USER_KEY_HERE

### REST API (curl / HTTP)

Base URL: https://api.boostops.io/api/v1
Auth: Authorization: Bearer bops_sk_USER_KEY_HERE

## Recommended Agent Workflows

### First-time setup
1. GET /api/v1/apps — see what apps the user has (note the app IDs)
2. GET /api/v1/portfolio/overview — studio-wide DAU, new users, revenue from Firebase/GA4
3. GET /api/v1/portfolio/summary — studio-wide KPIs from the ETL pipeline

### "How are my games doing?"
1. GET /api/v1/portfolio/overview — high-level DAU, revenue, new users (from Firebase/GA4)
2. GET /api/v1/apps/:appId/overview — per-app DAU, revenue, new users (from Firebase/GA4)
3. GET /api/v1/apps/:appId/anomalies — flag anything unusual

### "What's my ad spend / ROAS?"
1. GET /api/v1/apps/:appId/metrics — daily metrics including ad revenue
2. GET /api/v1/apps/:appId/attribution — which campaigns are driving installs

### "Are there any problems?"
1. GET /api/v1/apps/:appId/health — crash rates, ANR, store vitals
2. GET /api/v1/apps/:appId/reviews?rating=1,2 — recent negative reviews
3. GET /api/v1/apps/:appId/anomalies — automated anomaly detection

### "How are my reviews?"
1. GET /api/v1/apps/:appId/reviews — recent reviews across all stores
2. GET /api/v1/apps/:appId/health — includes store ratings

## REST API Endpoints

Every response includes `_provenance` so you know where data comes from.

### Overview (3rd-party reported — Firebase/GA4)
GET /api/v1/apps/:appId/overview    — Per-app DAU, new users, revenue
GET /api/v1/portfolio/overview      — Studio-wide rollup of overview data

### ETL Pipeline (platform reported)
GET /api/v1/apps/:appId/metrics     — Installs, revenue, DAU from ETL
GET /api/v1/portfolio/summary       — Studio-wide KPIs from ETL

### Attribution & Analysis
GET /api/v1/apps                    — List apps (scope: read:apps)
GET /api/v1/apps/:appId/attribution — Channel-level attribution (scope: read:attribution)
GET /api/v1/apps/:appId/anomalies   — Anomaly detection (scope: read:metrics)
GET /api/v1/apps/:appId/revenue     — Revenue breakdown (scope: read:metrics)
GET /api/v1/apps/:appId/installs    — Install metrics (scope: read:metrics)
GET /api/v1/apps/:appId/reviews     — Reviews and ratings (scope: read:apps)
GET /api/v1/apps/:appId/health      — App health assessment (scope: read:apps)
GET /api/v1/studio                  — Studio info (scope: read:apps)
GET /api/v1/dashboard               — Full dashboard in one call (scope: read:portfolio)

## Data Provenance

Each response has a `_provenance` field:
- `third_party_reported` — Direct from Firebase/GA4 or App Store Connect. Use /overview endpoints.
- `platform_reported` — Processed through the BoostOps ETL pipeline. Use /metrics endpoints.
- `attribution_derived` — Install splits from attribution providers (SKAN, ASA, MMP).
- `computed` — Calculated by BoostOps (anomalies, health scores).

## Common Parameters

- start_date=YYYY-MM-DD — start of date range
- end_date=YYYY-MM-DD — end of date range
- days=7 (or 14, 30, 90) — lookback period (alternative to start/end)
- 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 GET /api/v1/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
- 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://app.boostops.io/openapi.json