openapi: 3.0.3
info:
  title: App Store API — iOS App Data, Reviews, Charts & Search
  version: 1.0.0
  contact:
    name: AppSigma
    url: https://appsigma.io
  description: |
    The **App Store API** by [AppSigma](https://appsigma.io) is a REST API
    for the Apple App Store. Look up any iOS app, pull reviews and ratings,
    track chart positions and price changes, browse Apple's editorial items
    and in-app events, and run free-text search — all from one
    well-documented HTTP endpoint, returning JSON.

    This is **not** App Store Connect. App Store Connect lets a developer
    manage *their own* apps (sales, builds, TestFlight). The AppSigma App
    Store API lets you query *every* public app on the iOS App Store —
    including competitors — without scraping, parsing HTML, or running a
    headless browser. If you've ever reached for an "App Store scraper",
    the iTunes Search API, or a homemade parser of `apps.apple.com`, this
    API replaces all of them with a stable, versioned contract.

    ## What you can build

    - **Competitive intelligence** — monitor competitor pricing, ratings, version
      cadence, and chart movement across countries.
    - **ASO (App Store Optimization) tooling** — track keyword rankings, review
      sentiment, screenshot updates, and metadata changes.
    - **Market research dashboards** — pull Top Free / Top Paid / Top Grossing
      charts by country and genre, with daily history.
    - **Review monitoring & response** — stream new App Store reviews with
      score, country, version, and developer-response data.
    - **Price-drop and discount alerts** — historical `price-changes` per app
      across currencies.
    - **App discovery products** — paginate the App Store catalog with rich
      filters (genre, device, price range, ad-supported, etc.).

    ## Coverage

    - All public iOS apps on the Apple App Store (iPhone, iPad, Mac, Apple
      Watch, Apple TV, Vision Pro).
    - All Apple-supported storefronts / countries (ISO 3166-1 alpha-2 codes).
    - Top Free, Top Paid, and Top Grossing charts, current and historical.
    - Apple-authored editorial items ("Today" stories, app collections) and
      in-app events.
    - User reviews with author, score, version, vote count, and developer
      response.

    ## Conventions

    - **REST.** Resources are nouns (`/applications`, `/developers`,
      `/charts/positions`); verbs are HTTP methods. All responses are JSON.
    - **Pagination.** Collections accept `page` (1-based) and `perPage`. Each
      response includes `currentPage`, `lastPage`, `perPage`, `total`.
    - **Identifiers.** App Store IDs are Apple's numeric `trackId` (e.g.
      `544007664` for YouTube). They're stable across releases and across
      countries.
    - **Timestamps.** ISO 8601 strings in UTC unless documented otherwise
      (a few histogram endpoints expose Unix epoch `timestamp`s).
    - **Country codes.** ISO 3166-1 alpha-2, lowercase or uppercase accepted
      (e.g. `us`, `gb`, `de`, `jp`).
    - **Errors.** Every 4XX response uses the shared `Error` schema with a
      stable `code`, a human `message`, and an optional `requestId` for
      support tickets.

    ## Authentication

    Every request must include an API key in the `X-API-Key` header. Keys
    are issued per organization from the AppSigma dashboard. Treat your key
    as a secret and keep it server-side — anyone who has it can spend your
    credits. Browser use isn't hard-blocked (that's what lets the **Send**
    buttons in these docs work), but a real key belongs in server-to-server
    calls, not a mobile app or browser bundle.

    ## Try it free — no key required

    Don't have a key yet? Use the public **demo key** to run real requests
    right here in the browser:

    ```
    X-API-Key: demo
    ```

    Every **Send** button in these docs is pre-filled with it. Demo
    responses are **real, live Apple App Store data** — not mocks or fixtures
    — but the demo key is scoped to a small curated slice so it stays free
    and abuse-resistant:

    - **Two apps — YouTube (`544007664`) and Facebook (`284882215`).**
      `GET /applications/{id}` for either, plus all of their sub-resources
      (reviews, versions, ratings, price changes, chart history, …), work in
      demo; any other application ID returns `403`.
    - **A few search terms — `youtube`, `instagram`, `spotify`, `facebook`.**
      These work for both `GET /search/applications` and the `term` filter on
      `GET /applications`; any other term returns `403`.
    - **Two developers — Google LLC (`281956209`) and Meta Platforms
      (`284882218`).** `GET /developers/{id}` and their sub-resources
      (applications, events) work in demo; any other developer ID returns
      `403`.
    - **Charts** (`/charts/positions`, `/charts/history`) are fully browsable
      in demo. Events and editorial items are reachable by ID and scoped to a
      demo app or developer (e.g. `GET /applications/544007664/events`).

    Demo requests are **unbilled** — no credits are charged and no
    `X-API-Credits-*` headers are returned — and are rate-limited to keep
    the shared key fair. For the full App Store catalog, sign up for a key.

    ## Credits

    Every request debits credits from your plan. Single-item GETs cost 1
    credit, aggregate / histogram endpoints cost 2, list endpoints cost 1
    per row returned, and `/search/applications` is a flat 5. When your
    balance is too low to cover a request, the API returns
    `402 Payment Required` with the `payment_required` error code. Top up
    or upgrade to continue.

    ## Rate limiting

    Endpoints are rate-limited per API key. When you exceed the limit, the
    API returns `429 Too Many Requests` with a `Retry-After` header in
    seconds. Back off and retry.

    ## Source data

    Data is sourced directly from Apple — the iOS App Store catalog, the
    iTunes Search API for `/search/applications`, and Apple's public
    storefront feeds for charts, editorial items, and in-app events. We
    refresh continuously and expose only Apple-originated fields; no
    AI-generated summaries, no inferred tags. What you read is what Apple
    publishes.
servers:
  - url: https://api.appsigma.io/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Applications
    description: |
      Look up any iOS app on the Apple App Store by its numeric ID, or
      paginate the catalog with rich filters (genre, device, price range,
      release window, ad-supported, in-app purchases, achievements, etc.).
      Each application resource exposes Apple's full metadata: name,
      subtitle, developer, screenshots and preview videos, supported
      devices, in-app purchase tiers, ratings and content advisories,
      release date, current price, and chart positions.

      Sub-resources nested under `/applications/{applicationId}/...` cover
      everything you'd want to track over time for a single app — version
      history, price changes, ratings broken down by version, rating and
      review histograms, similar apps, editorial features, and chart
      history.
  - name: Charts
    description: |
      App Store chart data: who's #1 right now, and how positions moved
      over time. Three chart types are supported — Top **Free**, Top
      **Paid**, and Top **Grossing** — and you can filter by Apple genre
      ID (e.g. Games, Finance, Social Networking) or by maximum chart
      position.

      Use `/charts/positions` for a live snapshot of the current top
      apps, and `/charts/history` for daily history grouped by date and
      position — useful for "movers and shakers" reports, ASO trend
      analysis, and competitive monitoring.
  - name: Developers
    description: |
      App Store developer (publisher) profiles. Resolve the studio behind
      any app, then list every other app they ship and every in-app event
      they're running. Useful for portfolio analysis, identifying serial
      hit-makers, and grouping apps by parent company.
  - name: EditorialItems
    description: |
      Apple's hand-picked editorial content — the "Today" stories, app
      collections, and curated lists Apple surfaces inside the App Store.
      Editorial coverage is one of the strongest signals in App Store
      discovery; track it to see which apps Apple is featuring and when.
  - name: Events
    description: |
      In-app events — Apple's product surface for time-bound, in-app
      content (live competitions, premieres, season launches, special
      offers). Each event has start / end / promotion-start dates, a
      title and description, media, and the application it belongs to.
      Browse them per application (`/applications/{applicationId}/events`,
      optionally narrowed to a calendar day) or across a developer's whole
      catalog (`/developers/{developerId}/events`).
  - name: Search
    description: |
      Free-text search over the App Store, proxying Apple's iTunes Search
      API. Returns the same ranked result list a user would see when
      typing the query into the App Store, including any sponsored
      ("ads") slots Apple inserts at the top — so you can audit
      keyword rankings exactly the way real users encounter them.
paths:
  /applications:
    get:
      tags:
        - Applications
      operationId: listApplications
      summary: List and filter iOS App Store applications
      description: |
        Paginate the iOS App Store catalog with rich filters — by genre,
        device, price range, content advisory, release window, ad-supported
        flag, in-app purchases, achievements, free-text term, and more.
        Sort by popularity, recent price changes, biggest discount, lowest
        price, recently released, recently updated, or
        "best most-popular" (a popularity / rating composite).

        Returns trimmed `ApplicationShort` records suitable for catalog
        grids; use `GET /applications/{id}` for the full record on any
        selected app.
      parameters:
        - name: page
          in: query
          description: 1-based page number. Default `1`.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Items per page. Default `25`.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
        - name: ids
          in: query
          description: |
            Filter to a specific set of App Store track IDs (Apple's numeric
            app IDs). Repeat the parameter for each ID:
            `?ids=544007664&ids=284882215`.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: integer
              format: int64
            maxItems: 100
        - name: discounted
          in: query
          description: |
            When `true`, only apps whose price dropped within the last 30
            days. Pair with `sort=BIGGEST_DISCOUNT` for a discount-of-the-day
            feed.
          schema:
            type: boolean
        - name: sort
          in: query
          description: |
            Sort order for the result page.
            - `MOST_POPULAR` — default; popularity score.
            - `PRICE_UPDATE` — newest price changes first.
            - `BIGGEST_DISCOUNT` — largest absolute discount first.
            - `LOWEST_PRICE` — cheapest first.
            - `RECENTLY_RELEASED` — newest apps first.
            - `RECENTLY_UPDATED` — newest version first.
            - `BEST_MOST_POPULAR` — composite of popularity + rating.
          schema:
            type: string
            enum:
              - MOST_POPULAR
              - PRICE_UPDATE
              - BIGGEST_DISCOUNT
              - LOWEST_PRICE
              - RECENTLY_RELEASED
              - RECENTLY_UPDATED
              - BEST_MOST_POPULAR
        - name: primaryGenreId
          in: query
          description: Filter to apps whose Apple primary genre is this ID (e.g. `6014` for Games).
          schema:
            type: integer
          example: 6014
        - name: excludePrimaryGenreId
          in: query
          description: Exclude apps whose Apple primary genre is this ID.
          schema:
            type: integer
        - name: primaryGenre
          in: query
          description: Filter by primary genre slug (e.g. `games`, `social-networking`).
          schema:
            type: string
          example: games
        - name: filterLowRated
          in: query
          description: When `true`, hide apps with very low aggregate ratings or insufficient ratings to be reliable.
          schema:
            type: boolean
        - name: priceMin
          in: query
          description: Minimum price filter, in `priceCurrency` minor units (cents for USD).
          schema:
            type: integer
            minimum: 0
          example: 99
        - name: priceMax
          in: query
          description: Maximum price filter, in `priceCurrency` minor units.
          schema:
            type: integer
            minimum: 0
          example: 999
        - name: priceCurrency
          in: query
          description: ISO 4217 currency the `priceMin` / `priceMax` values are expressed in. Default `USD`.
          schema:
            type: string
            default: USD
        - name: minRatingScore
          in: query
          description: Minimum aggregate rating (0–5).
          schema:
            type: number
            minimum: 0
            maximum: 5
          example: 4
        - name: genreIds
          in: query
          description: Filter to apps tagged with any of these Apple genre IDs (repeat the parameter).
          style: form
          explode: true
          schema:
            type: array
            items:
              type: integer
        - name: device
          in: query
          description: Restrict to apps that run on this Apple device class.
          schema:
            type: string
            enum:
              - IPHONE
              - IPAD
              - IPOD
              - MAC
              - WATCH
              - APPLETV
              - REALITYDEVICE
          example: IPHONE
        - name: features
          in: query
          description: |
            Filter by Apple capability features. Repeat the parameter. Values
            include `hasSafariExtension`, `supportsGameController`,
            `supportsSiri`, `supportsArcade`, `supportsWallet`,
            `macOSCompatible`, `hasFamilyShareablePurchases`,
            `supportsAppleWatch`, `hasMessagesExtension`, `supportsVisionPro`.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: advisoryRating
          in: query
          description: Apple age rating (e.g. `4+`, `9+`, `12+`, `17+`).
          schema:
            type: string
          example: 4+
        - name: releasePeriodDays
          in: query
          description: Restrict to apps released in the last N days (use with `sort=RECENTLY_RELEASED`). Capped at `1825` (5 years).
          schema:
            type: integer
            minimum: 1
            maximum: 1825
          example: 30
        - name: preReleases
          in: query
          description: When `true`, include pre-release apps that aren't fully launched.
          schema:
            type: boolean
        - name: withAds
          in: query
          description: Apple "contains ads" filter. `true` = ad-supported apps only.
          schema:
            type: boolean
        - name: withAchievements
          in: query
          description: Filter to apps that integrate Game Center achievements.
          schema:
            type: boolean
        - name: term
          in: query
          description: |
            Free-text term to match against app name. For richer search use
            `GET /search/applications` instead — it proxies Apple's iTunes
            Search API and returns Apple's organic ranking plus sponsored
            slots.

            With the public **demo key**, this catalog endpoint must be scoped:
            pass an allowlisted `term` (`youtube`, `instagram`, `spotify`,
            `facebook`) or `ids` limited to the demo apps (`544007664`,
            `284882215`). An unscoped demo catalog page returns `403`.
          schema:
            type: string
          example: youtube
        - name: filterDeleted
          in: query
          description: When `true`, exclude apps that have been pulled from the App Store.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationShortPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{id}:
    get:
      tags:
        - Applications
      operationId: getApplication
      summary: Get a single iOS application by App Store ID
      description: |
        Look up the full record for one iOS App Store app — Apple's track
        ID is the numeric value at the end of any `apps.apple.com/...id<ID>`
        URL (e.g. `544007664` for YouTube). Returns the long-form
        `Application` schema with description, screenshots and preview
        videos, in-app purchases, supported devices, ratings, current
        price, and chart positions.

        Returns `404` if no app with this ID exists. Apps that have been
        pulled from the App Store are still returned; check
        `deletedInStoreAt` for the removal timestamp.
      parameters:
        - name: id
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
      responses:
        '200':
          description: Application record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/reviews:
    get:
      tags:
        - Applications
      operationId: listApplicationReviews
      summary: Get App Store reviews for an iOS application
      description: |
        Paginate App Store user reviews for one app. Filter by score
        (1–5), country, and sort order. Reviews include author, title,
        body, version, vote counts, and the developer's reply when
        present.

        Common use cases:
        - Review-monitoring dashboards (poll with `sort=NEWEST_FIRST`).
        - Sentiment analysis pipelines (filter `score=1` or `score=2` for
          negative-only feeds).
        - Multi-country review streams (`countries=us&countries=gb&countries=de`).
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Reviews per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
        - name: sort
          in: query
          description: |
            Sort order.
            - `NEWEST_FIRST` — most recently authored first (default).
            - `OLDEST_FIRST` — oldest first.
            - `LOWEST_SCORE_FIRST` — 1-star first, useful for triage.
            - `BIGGEST_SCORE_FIRST` — 5-star first.
          schema:
            type: string
            enum:
              - NEWEST_FIRST
              - OLDEST_FIRST
              - LOWEST_SCORE_FIRST
              - BIGGEST_SCORE_FIRST
        - name: score
          in: query
          description: Filter to reviews with this exact star score (1–5).
          schema:
            type: integer
            minimum: 1
            maximum: 5
          example: 1
        - name: countries
          in: query
          description: |
            ISO 3166-1 alpha-2 country codes — restrict to reviews from
            these storefronts. Repeat the parameter for each country
            (`?countries=us&countries=gb`).
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          example:
            - us
            - gb
      responses:
        '200':
          description: Paginated reviews.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/versions:
    get:
      tags:
        - Applications
      operationId: listApplicationVersions
      summary: Get version (release) history for an iOS application
      description: |
        Paginate every published version of one app, newest first. Each
        record includes the version string, Apple's "What's New" release
        notes, and the release date. Useful for ASO release-cadence
        analysis, changelog mining, and detecting silent vs. major updates.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Versions per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated version history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/similars:
    get:
      tags:
        - Applications
      operationId: listSimilarApplications
      summary: Get similar applications for an iOS app
      description: |
        Paginate apps Apple surfaces as similar / "you may also like" for
        a given app. Useful for competitor discovery and category-level
        competitive analysis.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Items per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated similar applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationShortPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/price-changes:
    get:
      tags:
        - Applications
      operationId: listApplicationPriceChanges
      summary: Get price-change history for an iOS application
      description: |
        Every observed price change for one app, newest first. Each entry
        records the new price, previous price, and signed difference.
        Use this to power discount alerts, build price-history charts,
        and verify that an app is genuinely discounted versus reverting
        to a baseline price.

        Prices are returned in integer **minor units** of `currency`
        (cents for USD). See `PriceChange` schema for details.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: daysPeriod
          in: query
          description: |
            Window in days to look back. `0` = all-time. Common values:
            `7`, `30`, `90`, `180`, `365`. Capped at `1825` (5 years).
          schema:
            type: integer
            minimum: 0
            maximum: 1825
          example: 90
      responses:
        '200':
          description: Price-change history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceChange'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/editorial-items:
    get:
      tags:
        - Applications
      operationId: listApplicationEditorialItems
      summary: Get Apple editorial items featuring an application
      description: |
        Apple-authored editorial coverage that includes this app — "Today"
        stories, app collections, "App of the Day" features, etc. Strong
        discovery signal; tracking which apps Apple is featuring (and
        when) is a common ASO use case.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Items per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated editorial items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditorialItemPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/events:
    get:
      tags:
        - Applications
      operationId: listApplicationEvents
      summary: List an app's Apple App Store in-app events
      description: |
        Paginate Apple in-app events for a single application — time-bound,
        in-app content surfaces Apple promotes inside the App Store (live
        competitions, premieres, season launches, special offers). Scope to a
        calendar day with `date`.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID of the application.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Events per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
        - name: date
          in: query
          description: |
            Filter to events occurring on a specific calendar day
            (`YYYY-MM-DD`). Matches against the event's start / end date
            window.
          schema:
            type: string
            format: date
          example: '2024-12-04'
      responses:
        '200':
          description: Paginated events for the application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/in-app-purchases:
    get:
      tags:
        - Applications
      operationId: listApplicationInAppPurchases
      summary: Get in-app purchases (IAPs) for an iOS application
      description: |
        Paginate the in-app purchase tiers an app exposes — consumables,
        non-consumables, and auto-renewing subscriptions. Subscription
        tiers include the billing period, free trial, and intro-offer
        metadata when present. Prices are in integer **minor units** of
        `currency` (cents for USD).
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: IAPs per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated in-app purchases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InAppPurchasePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/rating-histogram:
    get:
      tags:
        - Applications
      operationId: getApplicationRatingHistogram
      summary: Get daily rating histogram for an iOS application
      description: |
        Day-by-day breakdown of star ratings collected for one app. Each
        bucket carries the date, mean score for the day, count of ratings
        received, and the 1–5 star distribution. Use this to trend overall
        app health and detect quality regressions tied to specific releases.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: from
          in: query
          description: Start date (inclusive), ISO 8601 `YYYY-MM-DD`.
          schema:
            type: string
            format: date
          example: '2024-09-01'
        - name: to
          in: query
          description: End date (inclusive), ISO 8601 `YYYY-MM-DD`.
          schema:
            type: string
            format: date
          example: '2024-12-01'
      responses:
        '200':
          description: Rating histogram by date.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RatingHistogramItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/ratings-by-version:
    get:
      tags:
        - Applications
      operationId: listApplicationRatingsByVersion
      summary: Get ratings broken down by app version
      description: |
        Star ratings grouped by app version. Each row carries the version
        string, mean score, count of ratings on that version, and the 1–5
        distribution. Use this to spot quality regressions release-over-
        release — a version where mean score drops vs. its predecessor is
        a signal worth investigating.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
      responses:
        '200':
          description: Ratings by version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RatingByVersion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/review-histogram:
    get:
      tags:
        - Applications
      operationId: getApplicationReviewHistogram
      summary: Get review-volume histogram for an iOS application
      description: |
        Time-bucketed review counts for one app. Each bucket carries a
        Unix epoch `timestamp`, mean star score in the bucket, and the
        count of reviews authored within the bucket. Useful for tracking
        review velocity around launches, marketing pushes, and price
        changes.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: from
          in: query
          description: Start of the range as Unix epoch seconds.
          schema:
            type: integer
          example: 1725148800
        - name: to
          in: query
          description: End of the range as Unix epoch seconds.
          schema:
            type: integer
          example: 1733011200
      responses:
        '200':
          description: Review-volume histogram.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReviewHistogramItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /applications/{applicationId}/chart-history:
    get:
      tags:
        - Applications
      operationId: listApplicationChartHistory
      summary: Get App Store chart history for one application
      description: |
        Day-by-day record of where this app ranked on Apple's Top Free /
        Top Paid / Top Grossing charts (overall or scoped to a genre).
        The app-centric inverse of `GET /charts/history` — instead of
        asking "who held position X on date Y", you ask "where did this
        app rank, day by day".

        Common use cases: chart-presence tracking, "movers and shakers"
        visualizations, post-launch curve analysis.
      parameters:
        - name: applicationId
          in: path
          required: true
          description: Apple App Store track ID.
          schema:
            type: integer
            format: int64
          example: 544007664
        - name: type
          in: query
          description: Chart type. Omit to return history across all chart types.
          schema:
            type: string
            enum:
              - FREE
              - PAID
              - TOP_GROSSING
          example: FREE
        - name: genreId
          in: query
          description: |
            Apple genre ID to scope the chart slice. Omit (or pass nothing)
            for the overall, all-genres chart.
          schema:
            type: integer
          example: 6005
        - name: maxPosition
          in: query
          description: |
            Only include days where the app ranked at or above this position
            (e.g. `maxPosition=10` = appearances in the top 10).
          schema:
            type: integer
            minimum: 1
          example: 10
        - name: daysPeriod
          in: query
          description: |
            Window in days to look back. `0` = all-time. Common values:
            `1`, `7`, `30`, `90`, `180`, `365`. Capped at `1825` (5 years).
          schema:
            type: integer
            minimum: 0
            maximum: 1825
          example: 30
      responses:
        '200':
          description: Chart history for the application.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationChartHistoryItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /charts/positions:
    get:
      tags:
        - Charts
      operationId: listChartPositions
      summary: Get current App Store chart positions
      description: |
        Live snapshot of an Apple App Store chart — Top Free, Top Paid, or
        Top Grossing — optionally scoped to a single genre and trimmed to
        a maximum position.

        Returned in chart order (1 first). Each entry includes the app
        sitting at that slot plus its previous position, so you can
        compute movement (rank delta) without a second call.
      parameters:
        - name: type
          in: query
          required: true
          description: Which Apple chart to read.
          schema:
            type: string
            enum:
              - FREE
              - PAID
              - TOP_GROSSING
          example: FREE
        - name: genreId
          in: query
          description: |
            Apple genre ID to scope the chart (e.g. `6014` for Games). Omit
            for the overall chart across all genres.
          schema:
            type: integer
          example: 6014
        - name: maxPosition
          in: query
          description: |
            Trim the response to the top N positions. Omit for the full chart.
            With the `demo` key this is capped at 10 (higher values return
            `403`; omitting it returns the top 10).
          schema:
            type: integer
            minimum: 1
          example: 10
      responses:
        '200':
          description: Current chart positions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChartPosition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /charts/history:
    get:
      tags:
        - Charts
      operationId: getChartHistory
      summary: Get App Store chart history grouped by date and position
      description: |
        Historical chart snapshots laid out as a date → position matrix.
        Iterate `dates`, then for each date iterate `positions` in rank
        order (`"1"`, `"2"`, ...). Useful for "who held #1 last month"
        style queries and for movers-and-shakers reports.
      parameters:
        - name: type
          in: query
          required: true
          description: Which Apple chart to read.
          schema:
            type: string
            enum:
              - FREE
              - PAID
              - TOP_GROSSING
          example: FREE
        - name: genreId
          in: query
          description: Apple genre ID to scope. Omit for the overall chart.
          schema:
            type: integer
          example: 6014
        - name: maxPosition
          in: query
          description: |
            Trim each daily snapshot to the top N positions (default 10).
            With the `demo` key this is capped at 10 (higher values return `403`).
          schema:
            type: integer
            minimum: 1
          example: 10
        - name: daysPeriod
          in: query
          description: |
            Window in days to return (default 30, maximum 1825 — 5 years).
            With the `demo` key this is capped at 3 (higher values return `403`).
          schema:
            type: integer
            minimum: 1
            maximum: 1825
          example: 3
      responses:
        '200':
          description: Chart history matrix.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /developers/{id}:
    get:
      tags:
        - Developers
      operationId: getDeveloper
      summary: Get an App Store developer profile
      description: |
        Look up the publisher / studio behind any iOS app by Apple's
        developer (artist) ID. Returns portfolio-level stats — total app
        count, weighted aggregate rating, oldest and newest release dates,
        logo when available.
      parameters:
        - name: id
          in: path
          required: true
          description: Apple developer / artist ID.
          schema:
            type: integer
            format: int64
          example: 284882218
      responses:
        '200':
          description: Developer profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Developer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /developers/{developerId}/applications:
    get:
      tags:
        - Developers
      operationId: listDeveloperApplications
      summary: Get applications published by a developer
      description: |
        Paginate every iOS app a developer publishes on the App Store.
        Useful for portfolio analysis, identifying serial hit-makers, and
        grouping apps by parent company.
      parameters:
        - name: developerId
          in: path
          required: true
          description: Apple developer / artist ID.
          schema:
            type: integer
            format: int64
          example: 284882218
        - name: sort
          in: query
          description: Sort order. Currently only `MOST_POPULAR` is supported.
          schema:
            type: string
            enum:
              - MOST_POPULAR
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Items per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated developer's applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationShortPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /developers/{developerId}/events:
    get:
      tags:
        - Developers
      operationId: listDeveloperEvents
      summary: Get in-app events from a developer's applications
      description: |
        Paginate Apple in-app events across every app this developer
        publishes — useful for spotting cross-portfolio promotional
        pushes (e.g. a publisher running synchronized seasonal events
        across their game catalog).
      parameters:
        - name: developerId
          in: path
          required: true
          description: Apple developer / artist ID.
          schema:
            type: integer
            format: int64
          example: 284882218
        - name: page
          in: query
          description: 1-based page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Events per page.
          schema:
            type: integer
            minimum: 1
            default: 25
            maximum: 100
      responses:
        '200':
          description: Paginated events from the developer's applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /editorial-items/{id}:
    get:
      tags:
        - EditorialItems
      operationId: getEditorialItem
      summary: Get a single Apple App Store editorial item
      description: |
        Look up one Apple-authored editorial item by ID — typically a
        "Today" story or curated app collection. Returns the title,
        Apple's editorial body, the visual treatment hint
        (`displayStyle`), platforms targeted, and the last-published
        date.
      parameters:
        - name: id
          in: path
          required: true
          description: Apple's editorial-item ID.
          schema:
            type: integer
            format: int64
          example: 100000123456
      responses:
        '200':
          description: Editorial item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditorialItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /events/{id}:
    get:
      tags:
        - Events
      operationId: getEvent
      summary: Get a single in-app event by ID
      description: |
        Look up one Apple in-app event by ID. Returns the parent app,
        Apple's title and description, media, kind / badgeKind, and start /
        promotion-start / end timestamps.
      parameters:
        - name: id
          in: path
          required: true
          description: Apple in-app event ID.
          schema:
            type: integer
            format: int64
          example: 1655112042
      responses:
        '200':
          description: Event record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /search/applications:
    get:
      tags:
        - Search
      operationId: searchApplications
      summary: Search the iOS App Store for applications
      description: |
        Free-text search over the iOS App Store, proxying Apple's iTunes
        Search API. Returns the same ranked result list a user would see
        typing the query into the App Store, in the same order — including
        any sponsored ("ads") slot Apple inserts at the top of organic
        results. Use this to audit keyword rankings exactly the way real
        users encounter them, including paid placements.

        For catalog-style filtering (genre, price, device, etc.), use
        `GET /applications` instead.

        With the public **demo key** (`X-API-Key: demo`) this endpoint is
        limited to the terms `youtube`, `instagram`, `spotify`, and `facebook`;
        any other term returns `403`. A real key searches the full App Store.
      parameters:
        - name: term
          in: query
          required: true
          description: |
            Search term, exactly as the user would type it into the App
            Store search bar.
          schema:
            type: string
          example: youtube
        - name: country
          in: query
          description: |
            ISO 3166-1 alpha-2 country / storefront code. Apple ranks
            results per storefront — `us` and `de` will return different
            orders for the same term. Default `us`.
          schema:
            type: string
          example: us
      responses:
        '200':
          description: Apple search results, including any sponsored slots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchApplicationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Your API key, issued from the AppSigma dashboard. Pass it on every
        request in the `X-API-Key` header, and keep it server-side — treat it
        as a secret. No key yet? Use `demo` to make free, unbilled requests
        against a curated slice of live data (see the API description for what
        the demo key can reach).
  responses:
    BadRequest:
      description: Invalid request — malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: bad_request
            message: perPage must be between 1 and 100
            requestId: req_01HZX...
            details:
              field: perPage
              value: 5000
    Unauthorized:
      description: Missing or invalid API credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key
            requestId: req_01HZX...
    PaymentRequired:
      description: Insufficient credits to complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: payment_required
            message: Insufficient credits.
            requestId: req_01HZX...
    Forbidden:
      description: Authenticated but the current plan does not grant access to this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: forbidden
            message: Your plan does not include this endpoint
            requestId: req_01HZX...
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: not_found
            message: Application 12345 not found
            requestId: req_01HZX...
    TooManyRequests:
      description: Rate limit exceeded. Retry after the period indicated by the `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds the client should wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limited
            message: Too many requests
            requestId: req_01HZX...
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Stable machine-readable error code. Always lowercase snake_case.
            Known values: `unauthorized`, `forbidden`, `not_found`, `bad_request`,
            `rate_limited`, `payment_required`, `upstream_unavailable`,
            `internal_error`.
          example: unauthorized
        message:
          type: string
          description: Human-readable explanation.
        requestId:
          type: string
          description: Trace identifier; include when contacting support.
        details:
          type: object
          additionalProperties: true
          description: Optional structured context (e.g. validation field paths).
    Application:
      type: object
      description: |
        A full iOS App Store application record. This is the long-form detail
        view returned by `GET /applications/{id}` and includes everything Apple
        publishes about the app: identity, developer, genres, media, pricing,
        in-app purchases, ratings, current chart positions, and platform
        compatibility. For collection responses (`GET /applications`,
        `/charts/positions`, `/search/applications`, etc.) the trimmed
        `ApplicationShort` schema is used instead.
      properties:
        id:
          type: integer
          format: int64
          description: |
            Apple App Store track ID — Apple's stable numeric identifier for
            the app, equal to the `trackId` field in iTunes Search responses
            and the trailing number in `apps.apple.com/.../id<ID>` URLs.
          example: 284882215
        name:
          type: string
          description: Full app name as published on the App Store.
          example: Facebook
        shortName:
          type: string
          description: |
            Trimmed display name with the marketing tagline removed (anything
            after the first `-`, `:`, `—`, `–`, or `•` separator).
          example: Facebook
        subtitle:
          type: string
          description: Apple App Store subtitle line, displayed under the app name.
          example: Connect with friends, family
        description:
          type: string
          description: |
            The full long-form App Store description as authored by the
            developer. Plain text, line-break preserving.
          example: Where real friends share real moments...
        developer:
          description: |
            Publisher / studio behind the app. Returned as a compact reference
            (`{id, name}`) — call `GET /developers/{id}` for the full record.
          $ref: '#/components/schemas/DeveloperRef'
        primaryGenre:
          description: Apple's primary genre classification for the app.
          $ref: '#/components/schemas/Genre'
        genres:
          type: array
          description: All genres the app is listed under (primary first).
          items:
            $ref: '#/components/schemas/Genre'
        icon:
          type: string
          format: uri
          description: |
            App icon URL on Apple's CDN. The base URL is returned without an
            Apple size suffix so you can request any resolution by appending
            one (e.g. `/512x512bb.png`).
          example: https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/89/8c/06/898c0610-58c7-3a3c-3d2d-6a7e3c5a6f2e/Prod-0-2x.png/
        rating:
          description: Aggregate user rating across all versions and the current version.
          $ref: '#/components/schemas/Rating'
        releaseDate:
          type: string
          format: date-time
          description: ISO 8601 first-release date on the App Store.
          example: '2019-02-05T08:00:00.000Z'
        hasInAppPurchases:
          type: boolean
          nullable: true
          description: Whether the app offers in-app purchases.
          example: true
        price:
          description: Current price in the requested storefront, or `null` if free.
          $ref: '#/components/schemas/Price'
        supportsArcade:
          type: boolean
          nullable: true
          description: Whether the app is part of the Apple Arcade subscription.
          example: false
        supportedDevices:
          type: array
          description: |
            Human-readable list of devices the app supports — e.g. iPhone,
            iPad, iPod touch, Mac, Apple Watch, Apple TV, Vision Pro variants.
          items:
            type: string
          example:
            - iPhone
            - iPad
            - iPod touch
        hasAds:
          type: boolean
          nullable: true
          description: Apple's "contains ads" disclosure flag.
          example: false
        hasAchievements:
          type: boolean
          nullable: true
          description: Whether the app integrates with Game Center achievements.
          example: false
        deletedInStoreAt:
          type: string
          format: date-time
          nullable: true
          description: |
            Set when the app has been removed from the App Store. `null` for
            apps still live in the store.
          example: null
        screenshots:
          type: object
          description: |
            App Store screenshots, grouped by device class. Keys are device
            identifiers (`iphone`, `ipad`, `mac`, `appletv`, `watch`,
            `realityDevice`); values are arrays of `MediaItem` records in the
            order Apple displays them on the product page. Different devices
            have different aspect ratios, so each group is sized
            independently.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/MediaItem'
          example:
            iphone:
              - type: screenshot
                device: iphone
                url: https://is1-ssl.mzstatic.com/.../1290x2796.png
                width: 1290
                height: 2796
            ipad:
              - type: screenshot
                device: ipad
                url: https://is1-ssl.mzstatic.com/.../2048x2732.png
                width: 2048
                height: 2732
        videos:
          type: object
          description: |
            App preview videos, grouped by device class. Same shape as
            `screenshots` — keys are device identifiers, values are arrays
            of `MediaItem` video entries.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/MediaItem'
        inAppPurchases:
          type: array
          description: |
            Purchasable items inside the app — consumables, non-consumables, and
            subscriptions with their pricing tiers and trial offers.
          items:
            $ref: '#/components/schemas/InAppPurchase'
        advisories:
          type: array
          description: |
            Apple content advisories explaining the age rating (e.g.
            "Infrequent/Mild Profanity or Crude Humor").
          items:
            type: string
          example:
            - Infrequent/Mild Profanity or Crude Humor
        chartPositions:
          type: array
          description: |
            Chart slots the app currently occupies. Each entry includes the
            chart type (FREE / PAID / TOP_GROSSING), genre, position, and the
            previous position for movement tracking.
          items:
            $ref: '#/components/schemas/ChartPosition'
        bundleId:
          type: string
          nullable: true
          description: |
            Apple bundle identifier (reverse-DNS), unique per app. Useful when
            cross-referencing with other Apple tooling.
          example: com.facebook.Facebook
        minimumOsVersion:
          type: string
          nullable: true
          description: Minimum required iOS / iPadOS / macOS / watchOS version.
          example: '15.1'
        languageCodes:
          type: array
          description: ISO 639-1 language codes the app's metadata and UI support.
          items:
            type: string
          example:
            - EN
            - ES
            - FR
            - DE
            - JA
            - ZH
        fileSizeBytes:
          type: string
          nullable: true
          description: |
            Download size in bytes, returned as a string because Apple's value
            can exceed JavaScript's safe integer range.
          example: '367849472'
        contentRating:
          type: string
          nullable: true
          description: Apple age rating string (e.g. "4+", "12+", "17+").
          example: 12+
    DeveloperRef:
      type: object
      description: |
        Compact developer reference embedded inside other resources (e.g.
        `Application.developer`). Carries only the identifier and display name —
        fetch `GET /developers/{id}` for the full `Developer` record.
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          description: Apple App Store developer ID (artistId).
          example: 284882218
        name:
          type: string
          description: Developer / studio name as published on the App Store.
          example: Meta Platforms, Inc.
    ApplicationShort:
      type: object
      description: |
        Compact App Store application record returned in collection responses
        (`/applications`, `/charts/positions`, `/search/applications`,
        `/applications/{id}/similars`, etc.). Trimmed for list-view rendering;
        use `GET /applications/{id}` to fetch the full record with
        description, screenshots, videos, in-app purchases, and chart
        positions.
      properties:
        id:
          type: integer
          format: int64
          description: Apple App Store track ID.
          example: 284882215
        name:
          type: string
          description: Full app name on the App Store.
          example: Facebook
        shortName:
          type: string
          description: Trimmed display name with the marketing tagline removed.
          example: Facebook
        subtitle:
          type: string
          description: App Store subtitle.
          example: Connect with friends, family
        developer:
          description: |
            Minimal developer reference — only ID and name on this list-view
            schema. Use `GET /developers/{id}` for the full developer record
            with portfolio stats and release-date range.
          $ref: '#/components/schemas/DeveloperRef'
        primaryGenre:
          description: Primary genre classification.
          $ref: '#/components/schemas/Genre'
        icon:
          type: string
          format: uri
          description: App icon base URL on Apple's CDN (append size suffix).
          example: https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/89/8c/06/.../Prod-0-2x.png/
        rating:
          description: Aggregate user rating summary.
          $ref: '#/components/schemas/Rating'
        releaseDate:
          type: string
          format: date-time
          description: ISO 8601 first-release date.
          example: '2019-02-05T08:00:00.000Z'
        hasInAppPurchases:
          type: boolean
          nullable: true
          description: Whether the app offers in-app purchases.
          example: true
        price:
          description: Current price, or `null` if free.
          $ref: '#/components/schemas/Price'
        supportsArcade:
          type: boolean
          nullable: true
          description: Apple Arcade title flag.
          example: false
        supportedDevices:
          type: array
          description: Devices the app supports.
          items:
            type: string
          example:
            - iPhone
            - iPad
        hasAds:
          type: boolean
          nullable: true
          description: Apple "contains ads" disclosure flag.
          example: false
        hasAchievements:
          type: boolean
          nullable: true
          description: Game Center achievements integration flag.
          example: false
        deletedInStoreAt:
          type: string
          format: date-time
          nullable: true
          description: Set when the app has been pulled from the App Store.
          example: null
    ApplicationChartHistoryItem:
      type: object
      description: |
        One historical chart slot for a single app. Returned by
        `GET /applications/{applicationId}/chart-history` — the app-centric
        view of chart history (where this app ranked, day by day).
      properties:
        type:
          type: string
          description: Chart type.
          enum:
            - FREE
            - PAID
            - TOP_GROSSING
          example: FREE
        position:
          type: integer
          description: Position in the chart on this date (1-based).
          example: 4
        genreId:
          type: integer
          nullable: true
          description: Apple genre ID, or `null` for the overall chart.
          example: 6005
        previousPosition:
          type: integer
          nullable: true
          description: Position the previous day. `null` if the app entered the chart on this date.
          example: 6
        date:
          type: string
          format: date
          description: ISO 8601 date the snapshot was taken.
          example: '2024-12-04'
    ChartPosition:
      type: object
      description: |
        A current App Store chart slot occupied by an app — i.e. "this app
        is #N in chart X right now". Returned both standalone (under
        `Application.chartPositions`) and inside `/charts/positions`
        responses.
      properties:
        position:
          type: integer
          description: Current chart position, 1-based (1 = top of the chart).
          example: 3
        genreId:
          type: integer
          nullable: true
          description: |
            Apple genre ID this chart slice belongs to, or `null` for the
            overall (all-genres) chart.
          example: 6005
        chartType:
          type: string
          description: Which chart this position is from.
          enum:
            - FREE
            - PAID
            - TOP_GROSSING
          example: FREE
        application:
          description: The app sitting at this position.
          $ref: '#/components/schemas/ApplicationShort'
        createdAt:
          type: string
          format: date-time
          description: |
            Snapshot timestamp — when this chart position was recorded. Useful
            as an as-of marker, since charts refresh frequently.
          example: '2024-12-04T12:00:00.000Z'
        previousPosition:
          type: integer
          nullable: true
          description: |
            Position in the previous snapshot. `null` if the app is new to the
            chart. Subtract from `position` to get the rank delta.
          example: 5
    ChartHistoryEntry:
      type: object
      description: |
        One slot in the chart-by-date matrix returned by
        `GET /charts/history` — i.e. "on date D, position P was held by this
        app".
      properties:
        application:
          description: App at this position on this date.
          $ref: '#/components/schemas/ApplicationShort'
        position:
          type: integer
          description: Chart position (1-based).
          example: 1
        previousPosition:
          type: integer
          nullable: true
          description: Position on the previous day, or `null` if new to the chart.
          example: 2
        date:
          type: string
          format: date
          description: ISO 8601 snapshot date.
          example: '2024-12-04'
    ChartHistoryResponse:
      type: object
      description: |
        Chart-history payload, structured as a date → position matrix. Iterate
        `dates`, then for each date iterate `positions` to walk the chart in
        rank order.
      properties:
        dates:
          type: object
          description: |
            Map keyed by ISO 8601 date string (`YYYY-MM-DD`). Each value
            contains a `positions` map keyed by chart position (`"1"`,
            `"2"`, ...).
          additionalProperties:
            type: object
            properties:
              positions:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ChartHistoryEntry'
    Developer:
      type: object
      description: |
        An App Store developer (publisher) profile. Aggregates portfolio-level
        stats — total apps, weighted rating across the catalog, and the
        release window of their oldest and newest apps.
      properties:
        id:
          type: integer
          format: int64
          description: |
            Apple's developer / artist ID, equal to `artistId` in iTunes
            Search responses and stable across the catalog.
          example: 284882218
        name:
          type: string
          description: Developer's published name on the App Store.
          example: Meta Platforms, Inc.
        url:
          type: string
          format: uri
          description: Apple developer profile URL.
          example: https://apps.apple.com/us/developer/meta-platforms-inc/id284882218
        minReleaseDate:
          type: string
          format: date-time
          nullable: true
          description: Release date of the developer's oldest published app.
          example: '2008-07-11T07:00:00.000Z'
        maxReleaseDate:
          type: string
          format: date-time
          nullable: true
          description: Release date of the developer's most recently published app.
          example: '2024-09-19T07:00:00.000Z'
        applicationsRating:
          type: object
          nullable: true
          description: Aggregate rating across the developer's entire catalog.
          properties:
            averageScore:
              type: number
              description: Mean user rating, weighted by review count.
              example: 4.42
            count:
              type: integer
              description: Total review count summed across all of the developer's apps.
              example: 18230412
        applicationsCount:
          type: integer
          nullable: true
          description: Number of apps the developer currently publishes on the App Store.
          example: 12
        logo:
          type: string
          format: uri
          nullable: true
          description: Developer logo / brand image URL when available.
          example: null
    EditorialItem:
      type: object
      description: |
        An Apple-authored App Store editorial item — a "Today" story, app
        collection, or curated list. Editorial coverage is one of the
        strongest signals in App Store discovery; tracking which apps Apple
        is featuring (and when) is a common ASO use case.
      properties:
        id:
          type: integer
          format: int64
          description: Apple's stable editorial item ID.
          example: 100000123456
        name:
          type: string
          description: Editorial item title.
          example: Apps for Creative Pros
        title:
          type: string
          nullable: true
          description: Optional alternative title Apple uses on some surfaces.
          example: For the Creative Pro
        nameShort:
          type: string
          nullable: true
          description: Trimmed short variant of the title.
          example: Creative Pros
        tagline:
          type: string
          nullable: true
          description: One-line marketing tagline.
          example: Tools that turn ideas into work.
        label:
          type: string
          nullable: true
          description: Apple's section label (e.g. "App Of The Day", "Game Of The Day").
          example: Editor's Choice
        supportsArcade:
          type: boolean
          description: Whether the item is part of Apple Arcade-themed editorial.
          example: false
        kind:
          type: string
          nullable: true
          description: Apple editorial kind (e.g. `featuring`, `appBundle`, `editorial`).
          example: editorial
        description:
          type: string
          nullable: true
          description: Long-form editorial body Apple published.
          example: From sketching on iPad to final cut on Mac...
        url:
          type: string
          format: uri
          nullable: true
          description: Apple App Store deep link to the editorial story.
          example: https://apps.apple.com/us/story/id100000123456
        displayStyle:
          type: string
          description: Apple's visual treatment hint (e.g. `largeTile`, `featuredApps`).
          example: largeTile
        platforms:
          type: array
          description: Apple platforms the editorial item targets.
          items:
            type: string
          example:
            - iphone
            - ipad
        lastPublishedDate:
          type: string
          format: date-time
          description: ISO 8601 timestamp of Apple's most recent publish for this story.
          example: '2024-10-14T07:00:00.000Z'
    Event:
      type: object
      description: |
        An iOS App Store in-app event — Apple's surface for time-bound,
        in-app content (live competitions, premieres, season launches,
        limited-time offers). Each event belongs to one application and has
        start, promotion-start, and end dates.
      properties:
        id:
          type: integer
          format: int64
          description: Apple's stable in-app event ID.
          example: 1655112042
        application:
          description: The iOS app the event belongs to.
          $ref: '#/components/schemas/ApplicationShort'
        name:
          type: string
          description: Event display name.
          example: 'Season 7: Reckoning'
        subtitle:
          type: string
          description: One-line subtitle shown under the event name in the App Store.
          example: New ranked mode and rewards
        description:
          type: string
          description: Apple's published full description of the event (raw, not AI-generated).
          example: Compete in a brand-new ranked playlist...
        media:
          description: Promotional media (image / video) Apple displays for the event.
          $ref: '#/components/schemas/Media'
        kind:
          type: string
          description: Apple's event kind (e.g. `competition`, `premiere`, `liveEvent`).
          example: competition
        badgeKind:
          type: string
          description: |
            Visual badge Apple attaches to the event tile (e.g. `live`, `new`,
            `upcoming`).
          example: upcoming
        url:
          type: string
          format: uri
          description: Apple App Store deep link to the event.
          example: https://apps.apple.com/us/app/.../id389801252?l=en-US&pt=event/12345
        startDate:
          type: string
          format: date-time
          description: ISO 8601 timestamp the event becomes active.
          example: '2024-12-01T17:00:00.000Z'
        promotionStartDate:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp the event starts being promoted in the store
            (typically before `startDate`).
          example: '2024-11-25T17:00:00.000Z'
        endDate:
          type: string
          format: date-time
          description: ISO 8601 timestamp the event ends.
          example: '2024-12-15T17:00:00.000Z'
    Genre:
      type: object
      description: |
        Apple App Store genre / category. Apple's genre IDs are stable
        integers; use them anywhere a `genreId` parameter is accepted.
        Examples: Games (`6014`), Social Networking (`6005`), Finance
        (`6015`), Productivity (`6007`).
      properties:
        id:
          type: integer
          description: Apple genre ID.
          example: 6005
        name:
          type: string
          description: Apple's published name for the genre.
          example: Social Networking
        nameSlug:
          type: string
          nullable: true
          description: Lowercase, hyphenated slug derived from the genre name.
          example: social-networking
        parentId:
          type: integer
          nullable: true
          description: |
            Parent genre ID for sub-genres. `null` for top-level genres. Use
            this to walk Apple's genre tree.
          example: null
        applicationsCount:
          type: integer
          description: Number of apps currently catalogued under this genre.
          example: 184213
    InAppPurchase:
      type: object
      description: |
        An in-app purchase tier published by an iOS app — consumable,
        non-consumable, or auto-renewing subscription. Subscription metadata
        (period, free trial) is exposed under `subscription` when applicable.
        Price `amount` values are integer **minor units** of `currency`
        (cents for USD; `999` = `$9.99`).
      properties:
        name:
          type: string
          description: Localized display name of the IAP tier.
          example: Pro Monthly
        description:
          type: string
          description: Localized marketing description of the tier.
          example: Unlock all premium features.
        price:
          type: object
          description: Current price for the IAP tier.
          properties:
            amount:
              type: integer
              description: Price in `currency`'s minor units.
              example: 999
            currency:
              type: string
              example: USD
            formatted:
              type: string
              example: $9.99
        subscription:
          type: object
          nullable: true
          description: Subscription metadata. `null` for one-time purchases.
          properties:
            period:
              type: string
              description: |
                Apple's billing-period notation. Common values: `P1W`, `P1M`,
                `P2M`, `P3M`, `P6M`, `P1Y`.
              example: P1M
            trial:
              type: object
              nullable: true
              description: Free trial / introductory offer, if any.
              properties:
                period:
                  type: string
                  description: Trial duration in Apple's notation (e.g. `P7D`, `P14D`).
                  example: P7D
                price:
                  type: object
                  nullable: true
                  description: 'Intro price during the trial period (`amount: 0` for free trials).'
                  properties:
                    amount:
                      type: integer
                      description: Trial price in minor units. `0` for free trials.
                      example: 0
                    currency:
                      type: string
                      example: USD
                    formatted:
                      type: string
                      example: Free
        updates:
          type: array
          description: |
            Historical update events for this IAP tier (price changes, period
            changes). Each entry uses the same shape as the current record.
          items:
            type: object
    Media:
      type: object
      description: Promotional media asset attached to an editorial item or in-app event.
      properties:
        type:
          type: string
          description: Media kind (e.g. `image`, `video`).
          example: image
        url:
          type: string
          format: uri
          description: Full-size asset URL on Apple's CDN.
          example: https://is1-ssl.mzstatic.com/image/thumb/.../source.jpg
        previewUrl:
          type: string
          format: uri
          description: Lower-resolution preview / poster URL.
          example: https://is1-ssl.mzstatic.com/image/thumb/.../preview.jpg
        width:
          type: integer
          description: Asset width in pixels.
          example: 2400
        height:
          type: integer
          description: Asset height in pixels.
          example: 1200
        backgroundColor:
          type: string
          description: Apple-supplied dominant background color (hex without `#`).
          example: 0A84FF
        textColors:
          type: array
          description: Apple-supplied palette of foreground text colors (hex without `#`).
          items:
            type: string
          example:
            - FFFFFF
            - F2F2F7
    MediaItem:
      type: object
      description: |
        A single screenshot or app preview video from an iOS App Store
        product page. `width` / `height` are in pixels. Application
        screenshots and videos include a `device` field identifying which
        device class the asset targets (iPhone, iPad, Mac, etc.).
      properties:
        type:
          type: string
          description: Media kind.
          enum:
            - screenshot
            - video
          example: screenshot
        device:
          type: string
          description: Device class the asset targets.
          enum:
            - iphone
            - ipad
            - ipod
            - mac
            - watch
            - appletv
            - realityDevice
          example: iphone
        url:
          type: string
          format: uri
          description: Full-size asset URL on Apple's CDN.
          example: https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/.../source.png
        previewUrl:
          type: string
          format: uri
          nullable: true
          description: Lower-resolution preview / poster URL (videos primarily).
          example: null
        width:
          type: integer
          description: Asset width in pixels.
          example: 1290
        height:
          type: integer
          description: Asset height in pixels.
          example: 2796
        backgroundColor:
          type: string
          nullable: true
          description: Apple-supplied dominant background color (hex without `#`).
          example: 0A84FF
        textColors:
          type: array
          nullable: true
          description: Apple-supplied palette of foreground text colors (hex without `#`).
          items:
            type: string
          example:
            - FFFFFF
            - F2F2F7
    Price:
      type: object
      nullable: true
      description: |
        Current price in a single storefront. `null` when the app is free.
        Apps that monetize via in-app purchases or subscription show a free
        base price here and surface their tiers under
        `Application.inAppPurchases`.

        **Note on `amount`:** values are integer **minor units** of `currency`
        (e.g. cents for USD, pence for GBP, smallest unit per ISO 4217). For
        zero-decimal currencies like JPY the amount is the actual integer
        value. Use `formatted` for display.
      properties:
        formatted:
          type: string
          description: Apple-localized formatted price string with currency symbol.
          example: $9.99
        amount:
          type: integer
          description: |
            Price as an integer in `currency`'s minor units (cents for USD;
            i.e. `999` = `$9.99`).
          example: 999
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        discount:
          type: boolean
          description: |
            `true` when the current price is below the previous observed price
            and the previous price changed within the last 30 days. Combine
            with `/applications/{applicationId}/price-changes` for the full
            history.
          example: false
    PriceChange:
      type: object
      description: |
        A single price-change event for an iOS app. Returned by
        `GET /applications/{applicationId}/price-changes`. The `createdAt`
        here marks when the price actually changed on the App Store, not when
        our database recorded it. `amount` values are integer **minor units**
        of `currency` (cents for USD; `299` = `$2.99`).
      properties:
        formatted:
          type: string
          description: Apple-localized formatted price after the change.
          example: $2.99
        amount:
          type: integer
          description: New price in `currency`'s minor units.
          example: 299
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp the price changed.
          example: '2024-11-29T08:00:00.000Z'
        previous:
          type: object
          nullable: true
          description: |
            Price immediately before the change. `null` for the very first
            observed price.
          properties:
            formatted:
              type: string
              example: $4.99
            amount:
              type: integer
              description: Previous price in minor units.
              example: 499
        diff:
          type: object
          nullable: true
          description: |
            Signed difference (new minus previous) in minor units. Negative
            for discounts. `formatted` is sign-prefixed (`+` or `-`).
          properties:
            formatted:
              type: string
              example: '-$2.00'
            amount:
              type: integer
              example: -200
    Rating:
      type: object
      nullable: true
      description: |
        User rating summary for an app. Includes both the all-time aggregate
        and a current-version slice — useful for spotting quality regressions
        immediately after a release.
      properties:
        averageScore:
          type: number
          description: Mean star rating across all versions, 1–5 inclusive.
          example: 4.6
        count:
          type: integer
          description: Total number of star ratings (with or without text reviews) all-time.
          example: 7321008
        currentVersionScore:
          type: number
          description: Mean star rating for the latest published version only.
          example: 4.7
        currentVersionCount:
          type: integer
          description: Number of star ratings on the latest version.
          example: 12041
        histogram:
          type: object
          description: |
            Distribution of all-time ratings, keyed by star value (`"1"`–`"5"`).
            Sum equals `count`.
          additionalProperties:
            type: integer
          example:
            '1': 110000
            '2': 75000
            '3': 240000
            '4': 1320000
            '5': 5576008
    RatingByVersion:
      type: object
      description: |
        Rating breakdown for one specific app version. Returned by
        `GET /applications/{applicationId}/ratings-by-version` — useful for
        detecting quality regressions release-over-release.
      properties:
        version:
          type: string
          description: Version string the ratings belong to.
          example: 5.3.7
        score:
          type: number
          description: Mean star rating for this version, 1–5.
          example: 4.7
        count:
          type: integer
          description: Number of star ratings collected on this version.
          example: 12041
        histogram:
          type: object
          description: Distribution of ratings on this version, keyed by star value (`"1"`–`"5"`).
          additionalProperties:
            type: integer
          example:
            '1': 120
            '2': 80
            '3': 240
            '4': 1601
            '5': 10000
        versionCreatedAt:
          type: string
          format: date-time
          description: ISO 8601 release date of the version.
          example: '2024-09-19T07:00:00.000Z'
    RatingHistogramItem:
      type: object
      description: |
        One bucket of an app's rating histogram by date. Returned by
        `GET /applications/{applicationId}/rating-histogram` — useful for
        trending overall app health.
      properties:
        date:
          type: string
          format: date
          description: ISO 8601 date the histogram bucket represents.
          example: '2024-12-01'
        score:
          type: number
          description: Mean rating across all ratings collected on this date.
          example: 4.6
        count:
          type: integer
          description: Number of ratings collected on this date.
          example: 1822
        histogram:
          type: object
          description: Star-value distribution for the day (`"1"`–`"5"`).
          additionalProperties:
            type: integer
          example:
            '1': 30
            '2': 18
            '3': 64
            '4': 410
            '5': 1300
    Review:
      type: object
      description: |
        A single user review left on the Apple App Store. Reviews are scoped
        to one app version and one country storefront. Score is 1–5 inclusive.
        Developer responses appear in `developerResponse` when the developer
        has replied through App Store Connect.
      properties:
        id:
          type: integer
          format: int64
          description: Apple's stable review identifier.
          example: 11297461001
        author:
          type: string
          description: Display name the reviewer used on the App Store.
          example: Jane_R
        title:
          type: string
          description: Review title (one line).
          example: Best photo editor on iOS
        text:
          type: string
          description: Review body, plain text with line breaks preserved.
          example: Has every brush I need and the layer engine is fantastic...
        score:
          type: number
          description: Star rating, 1–5 inclusive (integer in practice; typed as number for forward compatibility).
          minimum: 1
          maximum: 5
          example: 5
        developerResponse:
          type: string
          nullable: true
          description: Developer's reply to the review, if any.
          example: Thanks for the kind words! We're working on more brushes for the next release.
        applicationVersion:
          type: string
          description: App version the review was posted against.
          example: 5.3.7
        createdAt:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp the review was authored on the App Store
            (mapped from Apple's `writtenAt`, not our internal row creation).
          example: '2024-08-12T14:32:11.000Z'
        voteCount:
          type: integer
          description: Number of helpfulness votes the review received.
          example: 42
        voteSum:
          type: integer
          description: |
            Sum of helpfulness votes (positive minus negative). Combined with
            `voteCount`, you can compute average helpfulness.
          example: 38
    ReviewHistogramItem:
      type: object
      description: |
        One bucket of an app's review-volume histogram. Returned by
        `GET /applications/{applicationId}/review-histogram`.
      properties:
        timestamp:
          type: integer
          description: Unix epoch timestamp (seconds) of the bucket boundary.
          example: 1733011200
        score:
          type: integer
          description: Mean star rating in this bucket, rounded to integer.
          example: 5
        count:
          type: integer
          description: Number of reviews authored within this bucket.
          example: 312
    SearchApplicationsResponse:
      type: object
      description: |
        App Store search response, mirroring what a user would see typing the
        query into the iOS App Store. `data` is the organic ranked list;
        `ads` is whatever sponsored slot Apple inserts at the top for the
        query. Both arrays use `ApplicationShort` records.
      properties:
        data:
          type: array
          description: Organic search results in Apple's rank order.
          items:
            $ref: '#/components/schemas/ApplicationShort'
        ads:
          type: array
          description: |
            Sponsored ("ads") results Apple injects above organic results
            for this query, when present. Empty array when the query has no
            sponsored slot.
          items:
            $ref: '#/components/schemas/ApplicationShort'
    Version:
      type: object
      description: |
        A published version of an iOS app. Returned by
        `GET /applications/{applicationId}/versions` for full release-history
        tracking — useful for ASO (App Store Optimization) cadence analysis
        and changelog mining.
      properties:
        name:
          type: string
          description: Version string as published by the developer.
          example: 5.3.7
        notes:
          type: string
          description: Apple's "What's New" release notes for this version.
          example: Bug fixes and performance improvements.
        releaseDate:
          type: string
          format: date-time
          description: ISO 8601 timestamp this version became available on the App Store.
          example: '2024-09-19T07:00:00.000Z'
    ApplicationShortPaginatedResponse:
      type: object
      description: |
        Paginated response wrapping a list of `ApplicationShort` records.
        Use the `currentPage` / `lastPage` / `perPage` / `total` envelope to
        drive pagination UIs and to know when you've reached the end.
      properties:
        data:
          type: array
          description: Page of applications, ordered per the request's `sort`.
          items:
            $ref: '#/components/schemas/ApplicationShort'
        currentPage:
          type: integer
          description: 1-based index of the page returned.
          example: 1
        lastPage:
          type: integer
          description: Last available page number for this query.
          example: 142
        perPage:
          type: integer
          description: Number of items per page (echoes the request's `perPage`, or the server default).
          example: 25
        total:
          type: integer
          description: Total number of items matching the query across all pages.
          example: 3541
    EditorialItemPaginatedResponse:
      type: object
      description: Paginated response wrapping a list of Apple App Store editorial items.
      properties:
        data:
          type: array
          description: Page of editorial items, most recently published first.
          items:
            $ref: '#/components/schemas/EditorialItem'
        currentPage:
          type: integer
          example: 1
        lastPage:
          type: integer
          example: 87
        perPage:
          type: integer
          example: 25
        total:
          type: integer
          example: 2156
    EventPaginatedResponse:
      type: object
      description: Paginated response wrapping a list of in-app events.
      properties:
        data:
          type: array
          description: Page of in-app events.
          items:
            $ref: '#/components/schemas/Event'
        currentPage:
          type: integer
          example: 1
        lastPage:
          type: integer
          example: 12
        perPage:
          type: integer
          example: 25
        total:
          type: integer
          example: 287
    InAppPurchasePaginatedResponse:
      type: object
      description: Paginated response wrapping a list of in-app purchase tiers.
      properties:
        data:
          type: array
          description: Page of in-app purchases.
          items:
            $ref: '#/components/schemas/InAppPurchase'
        currentPage:
          type: integer
          example: 1
        lastPage:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 25
        total:
          type: integer
          example: 6
    ReviewPaginatedResponse:
      type: object
      description: |
        Paginated response wrapping a list of App Store reviews for a single
        application.
      properties:
        data:
          type: array
          description: Page of reviews.
          items:
            $ref: '#/components/schemas/Review'
        currentPage:
          type: integer
          example: 1
        lastPage:
          type: integer
          example: 4012
        perPage:
          type: integer
          example: 25
        total:
          type: integer
          example: 100307
    VersionPaginatedResponse:
      type: object
      description: Paginated response wrapping the version history of an iOS app.
      properties:
        data:
          type: array
          description: Page of versions, newest first.
          items:
            $ref: '#/components/schemas/Version'
        currentPage:
          type: integer
          example: 1
        lastPage:
          type: integer
          example: 8
        perPage:
          type: integer
          example: 25
        total:
          type: integer
          example: 187
