Upgrade Guide: v2 to v3

While we've kept a similar data structure between versions for upgrade ease, there are several breaking changes that you will need to account for. All data structures and fields are described in the Swagger documentation.

Numeric IDs are Deprecated in Favor of UUIDs

In version 2, each content item exposed two identifiers:

  • A numeric ID (e.g. 123456)
  • A UUID (e.g. 550e8400-e29b-41d4-a716-446655440000)

In version 3+, the numeric ID has been removed and UUIDs are now the single, canonical identifier for all content items.

Benefits of UUIDs

  • Global uniqueness - UUIDs are unique across systems, environments, and time. This prevents collisions when data is merged, replicated, or cached across regions or services.
  • Better support for distributed systems - UUIDs can be generated independently without coordination, making them ideal for modern, horizontally scaled architectures.
  • Improved security and predictability - UUIDs are non-sequential, reducing the risk of ID enumeration and unintended data access.
  • Long-term stability - UUIDs remain stable even if internal database structures change, which allows us to evolve our backend without breaking external integrations.
  • Alignment with industry standards - UUIDs are widely supported across languages, databases, and tooling. Many client libraries already include first-class UUID handling.

How to Migrate from Numeric IDs (v2) to UUIDs (v3)

If your integration relied on numeric IDs in v2, you will need to have UUIDs stored with any content before upgrading to v3.

  1. Identify where numeric IDs are stored.
  2. Create a new field in your database to hold the UUID in parallel with the numeric ID. This field should be a UUID or VARCHAR depending on your database type.
  3. Write a script to retrieve and store the UUID for each item using your existing v2 API key and content endpoints, cross-referencing by the numeric ID.
  4. Check your integration for locations where you match results from the API with your existing results by numeric ID and switch to matching by UUID.

Return to top

Changed Field Names & Data Structures

While most field names and their format have stayed the same and are named semantically, several are different. See this chart for the most recent field names.

Version 2 Name

Version 3 Name

Change

uuid

id

UUID is now the canonical identifier. The Version 2 uuid field has been removed.

channel

mediaType

Name change only

themes

topics
  • Version 3+ has a completely different set of possible values.
  • Values that appear the same as in Version 2 will still have a different ID.
  • Values are now hierarchal.
  • For a complete list of values, query the /reviews/terms/topics endpoint.

reviewTopPicks

relatedLists

Name change only

product.cast, product.directors, product.genres, product.networks, product.studios, etc...

NO CHANGE

Data structure change. See Swagger documentation.

--

contentGrid[type].isPositive

New field. Shows whether this content grid item is a positive (higher value is great) or negative (higher value is a concern)

--

contentGrid[type].displayFlag

New field. Provides information for visually flagging this content grid value. See the Style Guide for details.

product.uuid, product.id, product.langcode, product.images

--

Removed fields

product.releaseDate

product.releaseDates

Renamed field

(Movies) product.rating.text

--

Removed field

(TV) product.platforms

--

Removed fields

(TV) product.types

product.type

Renamed field

(Apps) product.platforms, product.prices, product.priceStructure, product.requirements, product.size, product.version, product.specialNeeds, product.assistive

--

Removed fields

(Books) product.formats

--

Removed field

(Books) product.pages

product.length

Renamed field

(Books) product.types

product.type

Renamed field

(Games) product.priceStructure, product.platforms, product.prices, product.specialNeeds, product.assistive

--

Removed fields

(Websites) product.priceStructure, product.prices, product.specialNeeds, product.references, product.releaseDate

--

Removed fields

Return to top

Response Schema

All responses--whether a successful request or error--will use the following schema. HTTP status codes are still used. For examples and more details about fields, see the documentation for the endpoint(s) you will be calling. See the Swagger documentation for more details.


{ 
    "request": { 
        "url": "/api/v3/reviews", 
        "method": "GET", 
        "version": "3.0.0", 
        "timestamp": 1770142481821 
    }, 
    data: [], 
    error: null, 
    pagination: {} 
}

Return to top