# API reference

The initial versioned HTTP surface, generated from the shared endpoint contract.

## Competitors

GET /competitors, /competitors/categories, /competitors/{platform}/{storeId}, /similar, /organic and /aso read stored iOS catalogue evidence. GET /charts reads the latest bounded Apple chart snapshot, and GET /charts/apps/{storeId}/history reads that app’s dated rank history. POST /data-requests records deduplicated demand; it never starts collection.

## Creative library

GET /organic and /organic/{postId} search the copied public organic corpus. GET /paid-ads searches stored paid-ad observations. Saved organic and paid-ad commands use POST or DELETE on their /saved paths.

## Contract source

Each row in the endpoint table links to the request curl, JSON response and source for that operation. The shared public contract is the source of truth. This reference does not invent fields for spend, onboarding or native search volume.

## Endpoints

| Method | Path | Scope | MCP tool |
| --- | --- | --- | --- |
| GET | `/v1/competitors` | `context:read` | `search_competitors` |
| GET | `/v1/competitors/categories` | `context:read` | `list_competitor_categories` |
| GET | `/v1/competitors/{platform}/{storeId}` | `context:read` | `get_competitor` |
| GET | `/v1/competitors/{platform}/{storeId}/similar` | `context:read` | `get_similar_competitors` |
| GET | `/v1/competitors/{platform}/{storeId}/organic` | `context:read` | `get_competitor_organic` |
| GET | `/v1/competitors/{platform}/{storeId}/aso` | `context:read` | `get_competitor_aso` |
| GET | `/v1/competitors/{platform}/{storeId}/data-requests` | `context:read` | `list_competitor_data_requests` |
| POST | `/v1/competitors/{platform}/{storeId}/data-requests` | `content:write` | `request_competitor_data` |
| GET | `/v1/organic` | `context:read` | `search_organic_content` |
| GET | `/v1/organic/{postId}` | `context:read` | `get_organic_content` |
| GET | `/v1/organic/saved` | `context:read` | `list_saved_organic_content` |
| POST | `/v1/organic/{postId}/saved` | `content:write` | `save_organic_content` |
| DELETE | `/v1/organic/{postId}/saved` | `content:write` | `remove_saved_organic_content` |
| GET | `/v1/paid-ads` | `context:read` | `search_paid_ads` |
| GET | `/v1/admin/paid-ads/advertisers` | `content:write` | `admin_search_paid_ad_advertisers` |
| POST | `/v1/admin/paid-ads/preview` | `content:write` | `admin_preview_paid_ads` |
| POST | `/v1/admin/paid-ads/imports` | `content:write` | `admin_import_paid_ads` |
| GET | `/v1/admin/paid-ads/imports/{runId}` | `context:read` | `admin_get_paid_ad_import` |
| POST | `/v1/admin/paid-ads/imports/{runId}/retry` | `content:write` | `admin_retry_paid_ad_import` |
| POST | `/v1/admin/paid-ads/links` | `content:write` | `admin_link_paid_ads` |
| GET | `/v1/paid-ads/{platform}/{archiveId}` | `context:read` | `get_paid_ad` |
| POST | `/v1/paid-ads/{platform}/{archiveId}/transcript` | `content:write` | `generate_paid_ad_transcript` |
| POST | `/v1/paid-ads/{platform}/{archiveId}/analysis` | `content:write` | `analyze_paid_ad_creative` |
| POST | `/v1/paid-ads/{platform}/{archiveId}/saved` | `content:write` | `save_paid_ad` |
| DELETE | `/v1/paid-ads/{platform}/{archiveId}/saved` | `content:write` | `remove_saved_paid_ad` |
| GET | `/v1/aso/apps` | `context:read` | `list_aso_apps` |
| POST | `/v1/aso/apps` | `content:write` | `track_aso_app` |
| GET | `/v1/aso/apps/{appId}` | `context:read` | `get_aso_workstation` |
| PATCH | `/v1/aso/apps/{appId}` | `content:write` | `update_aso_app_role` |
| DELETE | `/v1/aso/apps/{appId}` | `content:write` | `remove_aso_app` |
| POST | `/v1/aso/apps/{appId}/keywords` | `content:write` | `add_aso_keywords` |
| DELETE | `/v1/aso/apps/{appId}/keywords/{keywordId}` | `content:write` | `remove_aso_keyword` |
| POST | `/v1/aso/apps/{appId}/refresh` | `content:write` | `refresh_aso_app` |
| GET | `/v1/aso/apps/{appId}/gap/{rivalStoreId}` | `context:read` | `get_aso_keyword_gap` |
| POST | `/v1/aso/app-search` | `content:write` | `search_ios_apps` |
| GET | `/v1/aso/keywords/{query}` | `context:read` | `explore_aso_keyword` |
| POST | `/v1/aso/keywords/{query}/refresh` | `content:write` | `refresh_aso_keyword` |
| POST | `/v1/competitors/intake/requested` | `content:write` | `request_ios_competitor` |
| POST | `/v1/competitors/intake/emerging-discovery` | `content:write` | `discover_emerging_ios_competitors` |
| GET | `/v1/competitors/{platform}/{storeId}/estimates/history` | `context:read` | `get_competitor_estimate_history` |
| POST | `/v1/competitors/{platform}/{storeId}/estimates/refresh` | `content:write` | `refresh_competitor_estimates` |
| GET | `/v1/competitors/{platform}/{storeId}/media` | `context:read` | `get_competitor_media` |
| GET | `/v1/competitors/intake/emerging` | `context:read` | `list_emerging_ios_competitors` |
| GET | `/v1/charts` | `context:read` | `get_apple_charts` |
| GET | `/v1/charts/apps/{storeId}/history` | `context:read` | `get_apple_chart_history` |