# Search iOS apps

Search the live App Store by name.

## Contract status

Preview contract: these routes and tools are implemented in the shared contract, but the public host, customer API access and OAuth flow have not been deployment verified.

## Endpoint: POST /v1/aso/app-search

- Method: `POST`
- Path: `/v1/aso/app-search`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `content:write`
- MCP tool: `search_ios_apps`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `term` | body | string | yes | App Store search text. |

## Known errors

- 400 invalid_request for an invalid filter, identity or limit.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing scope or unavailable preview access.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.
- 409 conflict when the write would duplicate an exclusive row.

## Request

This command calls Apple's public Search API immediately and is rate-limited to 20 searches per minute. Other ASO reads do not call Apple.

```
curl --request POST 'https://api.peekpanda.com/v1/aso/app-search' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --header 'content-type: application/json' \
  --data '{"term":"calorie"}'
```

## Response

Illustrative asoAppSearchPageSchema. Store facts are what Apple's search returned for this term.

```
{
  "data": [
    {
      "storeId": "0000000000",
      "name": "Example Calorie Tracker",
      "iconUrl": null,
      "developerName": "Example Labs",
      "primaryGenre": "Health & Fitness",
      "rating": 4.7,
      "ratingCount": 12450,
      "inCatalogue": true
    }
  ],
  "term": "calorie"
}

```

## Source

Apple public Search + Search hints. Difficulty from page-one rating counts Apple returns (page_one_median_rating_count: median page-one ratingCount, log10 scale, 1M ratings = 100). Demand is autocomplete order from apple_search_hints (rank + variant count), not volume and not Apple Ads popularity. Apple Ads Insights is not wired. Positions are observed_search_api_position from itunes.apple.com/search us/en_us.

## Refresh

This POST calls Apple immediately and is limited to 20 app searches per minute. GET ASO routes never call Apple. Other Apple collection stays on the 4s pacer and 2,500 calls per UTC day.