# Apple App Store Search & Reviews

**Apple App Store Search & Reviews** is an independently documented x402 Atlas bridge at https://appstore.use.x402atlas.com.
This document describes only this bridge; it does not aggregate routes, schemas,
or content from any other bridge.

## How payment works

Paid operations use the [x402 payment protocol](https://x402.org) and settle in
USDC. Atlas supports deployments on Base, Polygon, and Arbitrum, plus configured
Solana networks. This bridge currently advertises Arbitrum One (`eip155:42161`), Base (`eip155:8453`), Polygon (`eip155:137`), Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).

1. Send the HTTP request without a payment signature.
2. Read the `402 Payment Required` response. Its `accepts` entries are the
   authoritative network, asset, amount, and recipient options for that call.
3. Select an option, sign it with an x402-compatible wallet or SDK, and repeat
   the request with the `PAYMENT-SIGNATURE` header. The successful response is
   returned after verification and settlement.

TypeScript clients can automate the challenge, signing, and retry flow with
[`x402-fetch`](https://www.npmjs.com/package/x402-fetch) or
[`x402-axios`](https://www.npmjs.com/package/x402-axios). Fund a dedicated
wallet only with the working USDC balance it needs and keep that key separate
from treasury accounts.

## Pricing

Atlas route prices start at $0.005 per successful call. This bridge's fallback
price is $0.005; operations below state their exact configured price in
`x-x402` and `x-payment-info`. The live `402` challenge remains authoritative.

## Worked payment example

Request one documented operation without a signature to inspect its live terms:

```bash
curl -i 'https://appstore.use.x402atlas.com/product?country=us&product_id=1069513131'
# HTTP/1.1 402 Payment Required
# Read accepts[].network, asset, amount, and payTo from this response.
```

Sign one accepted option and repeat the identical request with the
`PAYMENT-SIGNATURE` header. Do not invent or cache payment terms; read them from
the current challenge.

## Use this API

- Interactive reference: https://appstore.use.x402atlas.com/docs
- OpenAPI 3.1 specification: https://appstore.use.x402atlas.com/openapi.json
- Agent-readable route corpus: https://appstore.use.x402atlas.com/llms.txt
- Endpoint index: https://appstore.use.x402atlas.com/index.json

Use the operation schemas and examples below to construct requests. Copy the
server URL, path, method, parameters, and request body from the operation you
want to call. Path and query examples are concrete and can be used directly.

## Atlas response metadata

Successful JSON responses include an additive top-level `_atlas` block, kept
separate from the bridge's data fields. `_atlas.docs` links this bridge's
`/llms.txt` corpus. `_atlas.related` suggests adjacent APIs, each with a callable
`url`, its own `docs` link, and a short `summary`. Suppress this block by sending
`X-Atlas-Meta: none` or by adding `?_atlas=0` to the request.

## Errors and compatibility

Validation failures use HTTP `400`. Paid operations may return `402` before
dispatch. Upstream and internal failures use the documented `5xx` responses.
Clients should rely on documented fields and tolerate additive response fields,
including `_atlas` unless they explicitly opt out.

## Protocol reference

- x402 protocol and SDKs: https://x402.org

## Apple App Store Search & Reviews

Docs: https://appstore.use.x402atlas.com/docs · OpenAPI: https://appstore.use.x402atlas.com/openapi.json

### GET /product

Apple App Store product details — full profile for a single app by product_id: rating, price, description, version history, screenshots & metadata as clean JSON.

Apple App Store product details: pass a numeric `product_id` (required — an app's App Store id, e.g. `1069513131`, from `/search`) to pull its full profile. Returns `{ queried_at, product }`, where `product` carries `id`, `title`, `snippet`, `developer`, `rating`, `rating_count`, `price`, `age_rating`, `logo`, `description`, `iphone_screenshots`, `ipad_screenshots`, `version_history` (release notes & dates) and `information` (seller, size, category, copyright). Optional `country` (two-letter, default `us`). An unknown `product_id` still returns `200` with a `note` hint (the lookup ran, so the request is billed).

**Price:** $0.02 per call.

Parameters:
- `country` (optional, string) — Optional two-letter store country (e.g. us, gb); maxLength: `2`; example: `"us"`
- `product_id` (required, string) — Numeric App Store app id (from /appstore/search); maxLength: `32`, pattern: `"^[0-9]+$"`; example: `"1069513131"`

Example:

```sh
curl 'https://appstore.use.x402atlas.com/product?country=us&product_id=1069513131'
```

Response example:

```json
{
  "product": {
    "age_rating": "12+",
    "developer": {
      "name": "Grailr LLC"
    },
    "id": "1069513131",
    "price": "Free",
    "rating": 4.8,
    "rating_count": "51K Ratings",
    "title": "CARROT Weather: Alerts \u0026 Radar"
  },
  "queried_at": "2026-07-11T12:00:00Z"
}
```

### GET /reviews

Apple App Store reviews — pull an app's user reviews by numeric product_id: title, text, rating, version, author & date, with paging & sort, as clean JSON.

Apple App Store reviews: pass a numeric `product_id` (required — an app's App Store id, e.g. `1069513131`, from `/search`) to pull its reviews. Returns `{ product_id, queried_at, info, reviews }`, where `info` carries `total_page_count`, `results_count` and `reviews_for_current_version`, and each review has `id`, `title`, `text`, `rating`, `review_date`, `reviewed_version`, `author` and `helpfulness_vote_information`. Page through with `page` (use `info.total_page_count`). Optional `sort` (`mostrecent` default, `mosthelpful`, `mostfavorable`, `mostcritical` — iOS store only) and `country` (two-letter, default `us`). No reviews returns `200` with an empty `reviews` list.

**Price:** $0.02 per call.

Parameters:
- `country` (optional, string) — Optional two-letter store country (e.g. us, gb); maxLength: `2`; example: `"us"`
- `page` (optional, integer) — Optional page number; minimum: `1`; example: `1`
- `product_id` (required, string) — Numeric App Store app id (from /appstore/search); maxLength: `32`, pattern: `"^[0-9]+$"`; example: `"1069513131"`
- `sort` (optional, string) — Optional order: mostrecent (default), mosthelpful, mostfavorable, mostcritical; allowed: ["mostrecent","mosthelpful","mostfavorable","mostcritical"], default: `"mostrecent"`; example: `"mostrecent"`

Example:

```sh
curl 'https://appstore.use.x402atlas.com/reviews?country=us&page=1&product_id=1069513131&sort=mostrecent'
```

Response example:

```json
{
  "info": {
    "results_count": 500,
    "total_page_count": 10
  },
  "product_id": "1069513131",
  "queried_at": "2026-07-11T12:00:00Z",
  "reviews": [
    {
      "author": {
        "name": "rainlover"
      },
      "id": "7417861364",
      "rating": 5,
      "review_date": "2026-07-01",
      "reviewed_version": "5.9.0",
      "text": "Accurate and hilarious.",
      "title": "Best weather app"
    }
  ]
}
```

### GET /search

Apple App Store search — find iOS apps by term and get id, developer, price, rating, genres, description, size, icon & screenshots as clean JSON.

Apple App Store search: pass a `term` (required, e.g. "weather" or "habit tracker") to search the App Store. Returns `{ term, queried_at, results }`, where each result is an app with `id`, `title`, `bundle_id`, `version`, `developer`, `price`, `rating`, `genres`, `age_rating`, `description`, `size_in_bytes`, `link`, `logos` and `screenshots`. Use an app's `id` with `/product` for the full profile or `/reviews` for its reviews. Optional `country` (two-letter, default `us`), `lang` (e.g. `en-us`), `num` (1–200, default 10) and `page` control localization and paging. A term with no matches returns `200` with an empty `results` list.

**Price:** $0.02 per call.

Parameters:
- `country` (optional, string) — Optional two-letter store country (e.g. us, gb); maxLength: `2`; example: `"us"`
- `lang` (optional, string) — Optional language code (e.g. en-us); maxLength: `12`; example: `"en-us"`
- `num` (optional, integer) — Optional results per page, 1–200 (default 10); default: `10`, minimum: `1`, maximum: `200`; example: `10`
- `page` (optional, integer) — Optional page number; minimum: `1`; example: `1`
- `term` (required, string) — App Store search query (app name, category, or keyword); maxLength: `200`; example: `"weather"`

Example:

```sh
curl 'https://appstore.use.x402atlas.com/search?country=us&lang=en-us&num=10&page=1&term=weather'
```

Response example:

```json
{
  "queried_at": "2026-07-11T12:00:00Z",
  "results": [
    {
      "bundle_id": "com.grailr.CARROTWeather",
      "developer": {
        "name": "Grailr LLC"
      },
      "id": 1069513131,
      "position": 1,
      "price": {
        "type": "Free"
      },
      "rating": [
        {
          "count": 51000,
          "rating": 4.8,
          "type": "App Store"
        }
      ],
      "title": "CARROT Weather: Alerts \u0026 Radar"
    }
  ],
  "term": "weather"
}
```

### GET /v2/product/{product_id}

Apple App Store product details (path variant) — full profile for a single app by product_id in the URL: rating, price, description, version history, screenshots & metadata as clean JSON.

Apple App Store product details: pass a numeric `product_id` (required — an app's App Store id, e.g. `1069513131`, from `/search`) to pull its full profile. Returns `{ queried_at, product }`, where `product` carries `id`, `title`, `snippet`, `developer`, `rating`, `rating_count`, `price`, `age_rating`, `logo`, `description`, `iphone_screenshots`, `ipad_screenshots`, `version_history` (release notes & dates) and `information` (seller, size, category, copyright). Optional `country` (two-letter, default `us`). An unknown `product_id` still returns `200` with a `note` hint (the lookup ran, so the request is billed).

**Price:** $0.02 per call.

Parameters:
- `product_id` (required path, string) — Numeric App Store app id (from /appstore/search); maxLength: `32`, pattern: `"^[0-9]+$"`; example: `"886427730"`
- `country` (optional, string) — Optional two-letter store country (e.g. us, gb); maxLength: `2`; example: `"us"`

Example:

```sh
curl 'https://appstore.use.x402atlas.com/v2/product/886427730?country=us'
```

Response example:

```json
{
  "product": {
    "age_rating": "12+",
    "developer": {
      "name": "Grailr LLC"
    },
    "id": "1069513131",
    "price": "Free",
    "rating": 4.8,
    "rating_count": "51K Ratings",
    "title": "CARROT Weather: Alerts \u0026 Radar"
  },
  "queried_at": "2026-07-11T12:00:00Z"
}
```

### GET /v2/product/{product_id}/reviews

Apple App Store reviews (path variant) — an app's user reviews by product_id in the URL: title, text, rating, version, author & date, with paging & sort, as clean JSON.

Apple App Store reviews: pass a numeric `product_id` (required — an app's App Store id, e.g. `1069513131`, from `/search`) to pull its reviews. Returns `{ product_id, queried_at, info, reviews }`, where `info` carries `total_page_count`, `results_count` and `reviews_for_current_version`, and each review has `id`, `title`, `text`, `rating`, `review_date`, `reviewed_version`, `author` and `helpfulness_vote_information`. Page through with `page` (use `info.total_page_count`). Optional `sort` (`mostrecent` default, `mosthelpful`, `mostfavorable`, `mostcritical` — iOS store only) and `country` (two-letter, default `us`). No reviews returns `200` with an empty `reviews` list.

**Price:** $0.02 per call.

Parameters:
- `product_id` (required path, string) — Numeric App Store app id (from /appstore/search); maxLength: `32`, pattern: `"^[0-9]+$"`; example: `"886427730"`
- `country` (optional, string) — Optional two-letter store country (e.g. us, gb); maxLength: `2`; example: `"us"`
- `page` (optional, integer) — Optional page number; minimum: `1`; example: `1`
- `sort` (optional, string) — Optional order: mostrecent (default), mosthelpful, mostfavorable, mostcritical; allowed: ["mostrecent","mosthelpful","mostfavorable","mostcritical"], default: `"mostrecent"`; example: `"mostrecent"`

Example:

```sh
curl 'https://appstore.use.x402atlas.com/v2/product/886427730/reviews?country=us&page=1&sort=mostrecent'
```

Response example:

```json
{
  "info": {
    "results_count": 500,
    "total_page_count": 10
  },
  "product_id": "1069513131",
  "queried_at": "2026-07-11T12:00:00Z",
  "reviews": [
    {
      "author": {
        "name": "rainlover"
      },
      "id": "7417861364",
      "rating": 5,
      "review_date": "2026-07-01",
      "reviewed_version": "5.9.0",
      "text": "Accurate and hilarious.",
      "title": "Best weather app"
    }
  ]
}
```