Versioning & Upgrade guide

Learn more about our version support policy and the steps you need to take to upgrade your app to a newer API version.

When backwards-incompatible changes are made to the API, we release a new, dated version. The current version is 2024-10-04. For information on all API updates, view our upgrade guide below.

By default, requests made to the API use your access token's default API version (you can see that version in the Prepr UI) unless you override it by setting the Prepr-Version header.

Support policy

Prepr guarantees technical assistance and security updates for each new version of the GraphQL API for at least 24 months.

Please note that we do not change your API version automatically to avoid breaking your code. Once you are ready to upgrade, please follow the instructions below.

How to upgrade to a newer GraphQL API version

Your API version controls the API behavior you see (for example, how your schema is generated and what fields you can request). When a major or breaking change is introduced to the API, Prepr releases a new version based on the release date. In this case, we encourage our customers to upgrade their GraphQL API versions as soon as possible.

To upgrade to a newer GraphQL API version, you need to generate a new access token for your Prepr environment as follows:

1. Go to Settings → Access tokens and click Add access token.

2. On the New access token details page, provide the name of the token. For example, the access token you use to retrieve all published content items can be titled Published. If you want to preview the unpublished items on your staging site, consider creating an additional Preview token.

3. Next, define permissions for this access token under GraphQL Permissions. Permissions allow you to choose which content item statuses are accessible for an access token. Read more about GraphQL permissions.

4. Click Save to confirm the settings.

Once you've created a new access token, you'll notice the new API version indicated on the Access tokens overview page. By default, the new access token uses the latest GraphQL API version on the token generation date.

Released GraphQL API versions

You can check out the previous Prepr GraphQL API releases below.

Version 2024-10-04

What's new

• Stack & Reference fields can now be configured as a single-item field. This removes unnecessary arrays when using the field with a single element. Support for this feature has been added to all previous versions up to version 2023-02-09.

What's changed

• A/B tests without a B variant will now return no element for B targeted visitors, instead of always defaulting to A.

Version 2024-06-12

What's new

• The Context Type is now extended with a new field variant_key. In the upcoming release of the Prepr UI, this key will make tracking conversions on A/B tests or Personalizations much easier.

• In preparation for the upcoming release of custom events, a new system field _event has been added to the schema. This field, which expects a name argument, return a count of events from the specified type.

• For existing Prepr environments ENUM types can now be set to legacy mode (returning as a STRING instead of a native ENUM type).

What's changed

• The specific event counter fields (_comments, _purchases, _votes, _clickthroughs, _shares) have been removed from the default schema. Instead, you can use the new field _event(name: Purchase) to achieve the same result.

• If a locale is requested that is not set up in your Prepr environment, it will now throw a clear error.

• The _Event enum now also will hold all custom create event types.

• The input on filtering on Customer Relation has changed from argument _type to event.

• The Enum CustomerRelationType has been removed from the schema.

• Locales in the _localizations field are now consistently returned in alphabetical order (A-Z). This replaces the previous behavior where locales were returned in a unpredictable order.

// Before 2024-06-11
query {
    ContentItems(
        where: {
            _typename_any : ["Post"]
            _customer_relation : {
                id : "ad5714b0-dea5-46b3-9386-0f109ebbe29b",
                _type : BOOKMARKED
            }
        }
    ) { // }
}

// After 2024-06-12
query {
    ContentItems(
        where: {
            _typename_any : ["Post"]
            _customer_relation : {
                id : "ad5714b0-dea5-46b3-9386-0f109ebbe29b",
                event : Bookmark
            }
        }
    ) { // }
}

Version 2024-05-15

What's new

We are very excited to bring you the long-awaited feature to add fields to Assets. It is now possible to define your own fields to keep track of asset-specific info like Copyright or Source in addition to the core asset fields for the title, description and the author. Now, it's also possible to enable localization for your assets. This means your editors can enter information about assets in the locale that is relevant for them.

What's changed

• If an API version is specified by using the HTTP header Prepr-Version and set to a non-existing version, this will now generate an exception.

Version 2024-03-26

What's new

We are thrilled to introduce the long-awaited Enumerations feature. We've broadened the Schema to allow you to create your own enumerations and use them in any model or component using the List field. The ability to reuse a single enumeration across multiple models and components results in a cleaner Schema.

What's changed

• All list fields are update to use the new Enumerations feature. The response type of all list fields is changed from String or String! to the matching enumeration type.
• All filters on list fields are updated from String to the matching enumeration type.
• Please review your migrated ENUM lists for entries that commence with a numerical character, as ENUM values do not permit starting with an integer.

Version 2024-01-31

What's new

• Stack fields are now available in components, making your schema's way more flexible.
• Filtering on content relations is now extended to Stack fields.
• We added new filters for all content reference, remote content and slug fields.

What's changed

• Slug NULL filtering
  If null is passed to the _slug_any filter, this release will return all content items without a set slug. The behavior until this version was that all items were returned.

query {
    Posts(
        where: {
            _slug_any : null
        }
    )
}

• Slug ANY filtering
  If an empty list is passed to the _slug_any filter, this release will return all content items with a set slug. The behavior until this version was that all items were returned.

query {
    Posts(
        where: {
            _slug_any : []
        }
    )
}

• Content reference filtering
  If an empty object is passed to any reference filter, this release will return all content items with at least one referenced item. The behavior until this version was that all items were returned.

query {
    Posts(
        where: {
            sections: {}
        }
    )
}

Version 2023-11-02

What's new

• Introducing Strict Mode Strict Mode is released in public beta, if you have any feedback on this new feature, please let us know.

Strict Mode means you get more accurate and reliable TypeScript types from your GraphQL schema.

When you enable Strict Mode, the resulting GraphQL type will be String!, for example, instead of String. When the exclamation mark is omitted then it means the field is a string that will never be null.

In other words, code generators produce the TypeScript type of string instead of string | null | undefined.

That means you won't have to handle those additional cases in your front end, and TypeScript won't complain if you write things like author.name.toLowerCase().

Some more

• All model Types now include a new field _last_published_on. This field returns the timestamp of the last time the item was published.
• Union reference fields can now also be filtered based on the reference ID, slug of typename.

What's changed

• If you enable Strict Mode, all fields in your model and components that are marked as required are now marked as non-null.
• For all types (except Asset) the _type field has been removed, use __typename instead.
• Collection queries now strictly enforce a pagination limit of 100.

Non-Null Markings

• For the types FacebookPost, InstagramPost, SoundCloudPost, SpotifyPlaylist, TikTokPost, TwitterPost and VimeoPost the url field is now marked as non-null to match the ApplePodcast type.

• For all model types, the event counters are now marked as non-null Integer fields.

• For the types _DateRange, _DateTimeRange and BusinessHours all fields are now marked as non-null.

• The BusinessHoursPeriod type fields open_day, open_time, close_day, close_time and is_closed are now marked as non-null.

Version 2023-06-30

What's new

• In this release, we've added a new recommendation algorithm to the API. All models now have a People Also Viewed recommendation query.
• An asset field can now be configured as a single-asset field. This removes unnecessary arrays when using an asset field with a single asset.
• The introduction of nested components has made content modeling in Prepr even more powerful. You can now embed one component into another, creating a parent-child relationship within a component.
• For complex filtering, we've added an OR filter to the collection filters.
• A new not_contains filter is available for all Text fields.

What's changed

• Internal links in the text will now remove the <a HTML element if the linked content item/asset is deleted or unpublished.

Version 2023-04-17

What's new

• Models & Components are extended with a new field _context to add more support options for analytics and SSR when using Personalization and A/B testing.
• The new _context field is added to the Model and Component interface to help keep queries clean.
• Stack field now also allows to personalize based on query input of Customer ID or Segment ID's; arguments personalize_for_country and personalize_for_segments are added.
• Huge speed improvement, especially for customers with complicated content models.

What's changed

• The Component field _id will now return the ID of the component instance in a content item instead of the ID of the used component.
• On Models the fields _ab_testing_active, _ab_testing_version and _ab_testing_variation are removed.
• The type PersonalizationAudience has been renamed to Context.
• The Content type has been extended with the new fields kind and variant_id to simplify implementation.
• On Models the _personalization field has been renamed to _context.
• On Components the _audience field has been renamed to _context.

Version 2023-02-09

What's new

• Introducing a new field type Stack; This new field makes it much easier to structure and compose your component-based web pages. When you add this field in your content models, you can add other items and components in a single step when composing the content.
• All Models and Components now reference to their specific Interface Types. This will make some queries much shorter since the overlapping default fields can now be queried together.
• On the all types query ContentItems we added the _slug_any filter to make it easier to find pages without knowing the type.
• We added new API permissions, with more fine-grained control on the access level of content items.
• It is now also possible to switch off schema introspection on the access token settings page

What's changed

• The asset field Url returns now by default a optimized url for images instead of the original uploaded file.

• The asset field argument player has been removed from the Url field.

• The personalized_ queries are removed, use the new Stack fields instead.

• The Component field _id is now marked as non-null.

• The argument locale on the singular and collection queries is now marked as non-null.

• We removed support for the beta version for Personalization (this affect all previous versions of the API).

How to Update In most cases this update doesn't require action from your side. Please review the changes mentioned above carefully.

Version 2023-01-10

What's new

• Introducing new Type Remote source.
• Filter collections on the Business Hour field types.
• Added new filters for Integer, Float, Date, DateTime and Date Range fields.
• Added popular sort for ContentItems query (multi type filtering).
• Improved error description when using an expired access token.
• Security and speed optimizations.

What's changed

• Content integration support is removed, please update your integration to the new Remote source type.
• Types ContentIntegration, ContentIntegrations, KeyValue and Number are removed.

How to Update For Remote Source fields in a content model or component the query changes as follows:

Before 2023-01-10:

query {
    Product( id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
 
        commercelayer { // Content Integration field
            _id
            data {
                key
                value
            }
        }
    }
}

Fields can now be specified in the Remote Source.

query {
    Product( id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
 
        commercelayer { // Remote Content field
            _id
            product_id
            name
            ....
        }
    }
}

Remote content fields in a dynamic content editor field are also updated, check out the details on the Dynamic content field page.

Version 2022-08-15

What's new

• With the introduction of the _localization field you are able to fetch all locales of a content item in just one query. Making it easier to create language switches in your apps.

• Extended the native support for Mux (opens in a new tab) video adding all cover formatting options and the new playback_id field.

• More speed improvements. What's changed

• Content models: The fields _locale, _localization and _locales are now only being added to your content model if localization is active in your Prepr environment.

• Content models: The fields __ab_testing_active, __ab_testing_version are now only being added to your content model if A/B testing is activated for that model.

• Content models: The field __ab_testing_active field now returns true if there is an active A/B test on that content item.

• Components: Reference fields now have their own Union types if referencing multiple content models.

• Components: The _type field is removed for components, use __typename instead.

• Asset: _id is now marked as Non-Nullable field.

• Asset: playback_id is added to easy implementation of the new Mux Player (opens in a new tab).

• Asset: the field cdn_files is removed for customers using Mux.

Version 2022-03-22

This is a minor release, the url field on image assets will now return the full image instead of a default cropped size if no size is specified.

If you want to keep a default crop, just specify the default cropped size (width:1920) in the query:

query {
    Recipe( locales : ["en-US", "fr-FR", "nl-NL"], id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
 
        image {
            url(width:1920)
        }
    }
}

Version 2022-02-15

Where & Sort Inputs

The Input types for Where filters and Sort filters are now using the singular name instead of the plural name of a content model. Queries need to be updated to reflect the new type name.

For example:

query ExampleQuery($where: RecipeWhereInput) {
  Recipes(where: $where) {
    items {
      title
    }
  }
}

Query before 2022-02-15:

query ExampleQuery($where: RecipesWhereInput) {
  Recipes(where: $where) {
    items {
      title
    }
  }
}

Similarity and Popularity

The queries Similar_ and Popular_ collections now use the plural name of a content model.

New query:

    Similar_Recipes {
        items {
            title
        }
    }

Query before 2022-02-15:

    Similar_Recipe {
        items {
            title
        }
    }

Removed _model field

In this version we removed the field _model to identify a content item. You should use __typename instead.

Publications renamed to ContentItems

To match the terminology used in Prepr the query Publications is renamed to ContentItems.

Version 2021-11-29

In this version we changed the default formatting of heading elements inside a Dynamic Content field. They now include HTML <hX></hX> tags by default. If you need the plain text, change the field in your query from body to text.

New formatted response:

query {
    "data": {
        "Page": {
            "dynamic_field": [
                {
                    "body": "<h1>Hi1</h1>"
                }
            ]
        }
    }
}

Response in version 2021-09-27:

query {
    "data": {
        "Recipe": {
            "dynamic": [
                {
                    "body": "Hi1"
                },
                {
                    "body": "H2"
                }
            ]
        }
    }
}