> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/app-store-1.md).

# App Store

The App Store service provides access to iOS application data including reviews, ratings, and app metadata.

## Endpoints

| Endpoint                      | Description                                     | Pagination |
| ----------------------------- | ----------------------------------------------- | ---------- |
| `GET /api/appstore/reviews`   | Get reviews for an application                  | Standard   |
| `GET /api/appstore/apps`      | Get a single application by App ID or Bundle ID | —          |
| `GET /api/appstore/search`    | Search applications by term                     | Standard   |
| `GET /api/appstore/similar`   | Get similar applications                        | —          |
| `GET /api/appstore/developer` | Get all applications by a developer             | —          |

## Get Reviews

Fetch reviews for an iOS app with standard pagination.

### Request

```http
GET /api/appstore/reviews
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter | Type    | Required | Description                                                        |
| --------- | ------- | -------- | ------------------------------------------------------------------ |
| `app_id`  | string  | Yes      | App Store app ID (numeric). May be supplied as `bundleId` instead. |
| `country` | string  | No       | Country code (default: `us`)                                       |
| `sort`    | string  | No       | Sort order: `recent`, `helpful`, `critical`                        |
| `limit`   | integer | No       | Results per page (default: 25, max: 100)                           |
| `cursor`  | string  | No       | Pagination cursor                                                  |

### Example

```bash
curl "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215&country=us&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Credit cost

1 credit per page.

### Response

```json
{
  "data": [
    {
      "id": "10293847561",
      "author": "HappyUser",
      "rating": 5,
      "title": "Best app ever",
      "content": "I've been using this app for years and it keeps getting better...",
      "date": "2024-01-15T10:30:00Z",
      "version": "5.2.1",
      "helpful_count": 42
    }
  ],
  "pagination": {
    "next_cursor": "eyJwYWdlIjoyLCJsaW1pdCI6MjV9",
    "has_more": true
  },
  "meta": {
    "credits_used": 1,
    "request_id": "req_abc123"
  }
}
```

## Get App

Returns one application. Provide exactly one of `appId` or `bundleId`.

### Request

```http
GET /api/appstore/apps
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter  | Type   | Required | Description                                                             |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| `appId`    | string | No\*     | App Store app ID (numeric). Pattern: `^\d{8,12}$`. Example: `389801252` |
| `bundleId` | string | No\*     | App bundle ID (max 255). Pattern: `^[A-Za-z0-9.]+$`                     |
| `country`  | string | No       | Country code (2 letters, ISO 3166-1 alpha-2)                            |
| `lang`     | string | No       | Language code. Pattern: `^[a-z]{2,3}(-[a-z]{2,3})?$`                    |

\* Provide exactly one of `appId` or `bundleId`.

### Example

```bash
curl "https://api.pullbay.com/appstore/apps?appId=389801252" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Credit cost

1 credit per request + 1 credit per item.

### Response

```json
{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": 389801252,
      "appId": "com.burbn.instagram",
      "title": "Instagram",
      "url": "https://apps.apple.com/us/app/instagram/id389801252?uo=4",
      "description": "Little moments lead to big friendships. Share yours on Instagram.",
      "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg",
      "genres": ["Photo & Video", "Social Networking"],
      "genreIds": ["6008", "6005"],
      "primaryGenre": "Photo & Video",
      "primaryGenreId": 6008,
      "contentRating": "12+",
      "languages": ["EN", "FR", "DE", "JA", "ES"],
      "size": "563586048",
      "requiredOsVersion": "16.3",
      "released": "2010-10-06T08:12:41Z",
      "updated": "2026-04-20T17:48:35Z",
      "releaseNotes": "Performance optimizations and stability improvements for a smoother, more reliable experience.",
      "version": "426.0.0",
      "price": 0,
      "currency": "USD",
      "free": true,
      "developerId": 389801255,
      "developer": "Instagram, Inc.",
      "developerUrl": "https://apps.apple.com/us/developer/instagram-inc/id389801255?uo=4",
      "developerWebsite": "http://instagram.com/",
      "score": 4.69066,
      "reviews": 28962365,
      "currentVersionScore": 4.69066,
      "currentVersionReviews": 28962365,
      "screenshots": ["https://is1-ssl.mzstatic.com/image/thumb/.../392x696bb.jpg"],
      "ipadScreenshots": [],
      "appletvScreenshots": [],
      "supportedDevices": ["iPhone5s-iPhone5s", "iPadAir-iPadAir", "iPhone16Pro-iPhone16Pro"]
    }
  ],
  "pricing": {
    "creditsCharged": 2
  }
}
```

## Search Apps

Search the App Store for applications matching `term`. Use `page` for pagination or `maxItems` for a one-shot bulk pull (mutually exclusive).

### Request

```http
GET /api/appstore/search
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter  | Type    | Required | Description                                                                  |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `term`     | string  | Yes      | Search term (min 1, max 255). Example: `ai dungeon`                          |
| `country`  | string  | No       | Country code (2 letters, ISO 3166-1 alpha-2)                                 |
| `lang`     | string  | No       | Language code. Pattern: `^[a-z]{2,3}(-[a-z]{2,3})?$`                         |
| `maxItems` | integer | No       | One-shot bulk pull (min 1, max 200). Mutually exclusive with `page`.         |
| `page`     | integer | No       | Page number (min 1, max 5). Mutually exclusive with `maxItems`. Example: `1` |

### Example

```bash
curl "https://api.pullbay.com/appstore/search?term=ai%20dungeon&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Credit cost

1 credit per request + 1 credit per item.

### Response

```json
{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": 389801252,
      "appId": "com.burbn.instagram",
      "title": "Instagram",
      "url": "https://apps.apple.com/us/app/instagram/id389801252?uo=4",
      "description": "Little moments lead to big friendships. Share yours on Instagram.",
      "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg",
      "genres": ["Photo & Video", "Social Networking"],
      "genreIds": ["6008", "6005"],
      "primaryGenre": "Photo & Video",
      "primaryGenreId": 6008,
      "contentRating": "12+",
      "languages": ["EN", "FR", "DE", "JA", "ES"],
      "size": "563586048",
      "requiredOsVersion": "16.3",
      "released": "2010-10-06T08:12:41Z",
      "updated": "2026-04-20T17:48:35Z",
      "releaseNotes": "Performance optimizations and stability improvements for a smoother, more reliable experience.",
      "version": "426.0.0",
      "price": 0,
      "currency": "USD",
      "free": true,
      "developerId": 389801255,
      "developer": "Instagram, Inc.",
      "developerUrl": "https://apps.apple.com/us/developer/instagram-inc/id389801255?uo=4",
      "developerWebsite": "http://instagram.com/",
      "score": 4.69066,
      "reviews": 28962365,
      "currentVersionScore": 4.69066,
      "currentVersionReviews": 28962365,
      "screenshots": ["https://is1-ssl.mzstatic.com/image/thumb/.../392x696bb.jpg"],
      "ipadScreenshots": [],
      "appletvScreenshots": [],
      "supportedDevices": ["iPhone5s-iPhone5s", "iPadAir-iPadAir", "iPhone16Pro-iPhone16Pro"]
    }
  ],
  "pagination": {
    "page": 1,
    "hasNextPage": null,
    "cursor": null,
    "offset": null
  },
  "pricing": {
    "creditsCharged": 2
  }
}
```

## Get Similar Apps

Returns applications similar to the supplied one. Provide exactly one of `appId` or `bundleId`.

### Request

```http
GET /api/appstore/similar
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter  | Type   | Required | Description                                                             |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| `appId`    | string | No\*     | App Store app ID (numeric). Pattern: `^\d{8,12}$`. Example: `389801252` |
| `bundleId` | string | No\*     | App bundle ID (max 255). Pattern: `^[A-Za-z0-9.]+$`                     |
| `country`  | string | No       | Country code (2 letters, ISO 3166-1 alpha-2)                            |
| `lang`     | string | No       | Language code. Pattern: `^[a-z]{2,3}(-[a-z]{2,3})?$`                    |

\* Provide exactly one of `appId` or `bundleId`.

### Example

```bash
curl "https://api.pullbay.com/appstore/similar?appId=389801252" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Credit cost

1 credit per request + 1 credit per item.

### Response

```json
{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": 389801252,
      "appId": "com.burbn.instagram",
      "title": "Instagram",
      "url": "https://apps.apple.com/us/app/instagram/id389801252?uo=4",
      "description": "Little moments lead to big friendships. Share yours on Instagram.",
      "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg",
      "genres": ["Photo & Video", "Social Networking"],
      "genreIds": ["6008", "6005"],
      "primaryGenre": "Photo & Video",
      "primaryGenreId": 6008,
      "contentRating": "12+",
      "languages": ["EN", "FR", "DE", "JA", "ES"],
      "size": "563586048",
      "requiredOsVersion": "16.3",
      "released": "2010-10-06T08:12:41Z",
      "updated": "2026-04-20T17:48:35Z",
      "releaseNotes": "Performance optimizations and stability improvements for a smoother, more reliable experience.",
      "version": "426.0.0",
      "price": 0,
      "currency": "USD",
      "free": true,
      "developerId": 389801255,
      "developer": "Instagram, Inc.",
      "developerUrl": "https://apps.apple.com/us/developer/instagram-inc/id389801255?uo=4",
      "developerWebsite": "http://instagram.com/",
      "score": 4.69066,
      "reviews": 28962365,
      "currentVersionScore": 4.69066,
      "currentVersionReviews": 28962365,
      "screenshots": ["https://is1-ssl.mzstatic.com/image/thumb/.../392x696bb.jpg"],
      "ipadScreenshots": [],
      "appletvScreenshots": [],
      "supportedDevices": ["iPhone5s-iPhone5s", "iPadAir-iPadAir", "iPhone16Pro-iPhone16Pro"]
    }
  ],
  "pricing": {
    "creditsCharged": 2
  }
}
```

## Get Developer Apps

Returns the list of applications published by a single developer.

### Request

```http
GET /api/appstore/developer
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter     | Type   | Required | Description                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `developerId` | string | Yes      | Developer ID (numeric). Pattern: `^\d{8,12}$`. Example: `389801255` |
| `country`     | string | No       | Country code (2 letters, ISO 3166-1 alpha-2)                        |

### Example

```bash
curl "https://api.pullbay.com/appstore/developer?developerId=389801255" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Credit cost

1 credit per request + 1 credit per item.

### Response

```json
{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": 389801252,
      "appId": "com.burbn.instagram",
      "title": "Instagram",
      "url": "https://apps.apple.com/us/app/instagram/id389801252?uo=4",
      "description": "Little moments lead to big friendships. Share yours on Instagram.",
      "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg",
      "genres": ["Photo & Video", "Social Networking"],
      "genreIds": ["6008", "6005"],
      "primaryGenre": "Photo & Video",
      "primaryGenreId": 6008,
      "contentRating": "12+",
      "languages": ["EN", "FR", "DE", "JA", "ES"],
      "size": "563586048",
      "requiredOsVersion": "16.3",
      "released": "2010-10-06T08:12:41Z",
      "updated": "2026-04-20T17:48:35Z",
      "releaseNotes": "Performance optimizations and stability improvements for a smoother, more reliable experience.",
      "version": "426.0.0",
      "price": 0,
      "currency": "USD",
      "free": true,
      "developerId": 389801255,
      "developer": "Instagram, Inc.",
      "developerUrl": "https://apps.apple.com/us/developer/instagram-inc/id389801255?uo=4",
      "developerWebsite": "http://instagram.com/",
      "score": 4.69066,
      "reviews": 28962365,
      "currentVersionScore": 4.69066,
      "currentVersionReviews": 28962365,
      "screenshots": ["https://is1-ssl.mzstatic.com/image/thumb/.../392x696bb.jpg"],
      "ipadScreenshots": [],
      "appletvScreenshots": [],
      "supportedDevices": ["iPhone5s-iPhone5s", "iPadAir-iPadAir", "iPhone16Pro-iPhone16Pro"]
    }
  ],
  "pricing": {
    "creditsCharged": 2
  }
}
```

## Finding app IDs

The `app_id` is the numeric ID in the App Store URL:

```
https://apps.apple.com/us/app/facebook/id284882215
                                          └────────┘
                                           app_id
```

## Country codes

Use ISO 3166-1 alpha-2 codes: `us`, `gb`, `de`, `fr`, `jp`, etc.

## Review object

| Field      | Type    | Description                   |
| ---------- | ------- | ----------------------------- |
| `id`       | string  | Unique review identifier      |
| `date`     | string  | ISO 8601 timestamp            |
| `userName` | string  | Reviewer username             |
| `userUrl`  | string  | URL to the reviewer's profile |
| `version`  | string  | App version reviewed          |
| `score`    | integer | Star rating (1–5)             |
| `title`    | string  | Review title                  |
| `text`     | string  | Review body text              |
| `url`      | string  | URL to the review             |
| `country`  | string  | Country code of the review    |

## Application object

| Field                   | Type      | Description                          |
| ----------------------- | --------- | ------------------------------------ |
| `id`                    | integer   | Numeric App Store ID                 |
| `appId`                 | string    | Bundle ID                            |
| `title`                 | string    | App name                             |
| `url`                   | string    | App Store URL                        |
| `description`           | string    | App description                      |
| `icon`                  | string    | Icon image URL                       |
| `genres`                | string\[] | Genre names                          |
| `genreIds`              | string\[] | Genre IDs                            |
| `primaryGenre`          | string    | Primary genre name                   |
| `primaryGenreId`        | integer   | Primary genre ID                     |
| `contentRating`         | string    | Age rating (e.g. `12+`)              |
| `languages`             | string\[] | Supported languages                  |
| `size`                  | string    | App size in bytes                    |
| `requiredOsVersion`     | string    | Minimum required OS version          |
| `released`              | string    | Initial release date (ISO 8601)      |
| `updated`               | string    | Last update date (ISO 8601)          |
| `releaseNotes`          | string    | Notes for the current version        |
| `version`               | string    | Current version                      |
| `price`                 | number    | Price                                |
| `currency`              | string    | Currency code                        |
| `free`                  | boolean   | Whether the app is free              |
| `developerId`           | integer   | Developer ID                         |
| `developer`             | string    | Developer name                       |
| `developerUrl`          | string    | Developer App Store URL              |
| `developerWebsite`      | string    | Developer website                    |
| `score`                 | number    | Overall rating                       |
| `reviews`               | integer   | Total review count                   |
| `currentVersionScore`   | number    | Rating for the current version       |
| `currentVersionReviews` | integer   | Review count for the current version |
| `screenshots`           | string\[] | iPhone screenshot URLs               |
| `ipadScreenshots`       | string\[] | iPad screenshot URLs                 |
| `appletvScreenshots`    | string\[] | Apple TV screenshot URLs             |
| `supportedDevices`      | string\[] | Supported device identifiers         |