Concepts
FreeStuff's API is in large parts merely a read only gateway to our Content Management System (CMS). In order to understand all the things the API exposes you need to understand how our CMS is constructed.
Don't worry, it's not complex.
Products
At the core of everything are products. A product is a free game, an ingame item in gamepass, or anything else the bot sends notifications for.
Each product is part of an Announcement and has both a Channel as it's type
and a ProductKind as it's kind
.
Additionally a product has some basic properties like a title, assets (logos, images), and description, it has pricing information about old and new prices in multiple currencies, as well as metadata in various forms. See the corresponding Data Model for a full list of properties.
Each product has a kind as described earlier. This value describes what kind of product it is. Usually it's a game, but others like dlc or loot for game pass or prime gaming are also possible. FreeStuff also has more types like art, ost, or other which are currently unused.
2025-03-01
. Newer versions might differ in details.Announcements
When we publish products to send to our official bots on Discord, Telegram and potentially others, as well as our API users like you, we're not publishing products individually. Instead we often bundle multiple products together because they have semantic relevance and/or because it allows us to more effectively distribute the products to our hundreds of thousands of subscribers.
An announcement describes such a collection of products. Every time we publish something a new announcement is created, even if it's just for a single product.
Each announcement goes into a Channel. All products belonging to that announcement also have the same Channel set as their type
.
Channels
FreeStuff supports different kinds of free games. There's games that have a temporary 100% discount, games that are available to play for a limited amount of time without you owning them, there's game pass and prime gaming, there's DLCs and additional content, etc.
Each of those is a channel. You might only be interested in a single one of those channels or you might be interested in multiple or all of them.
More channels may be added in the future but here is our current list:
Content Summary
FreeStuff has different Channels with different purposes.
A Channel is used to publish Announcements.
An Announcement is a collection of Products, all with the same type but of potentially different kinds.
Compatibility Dates
API v2 introduces compatibility dates. These act as versioning for the format of the data you can access through FreeStuff's API.
In simpler terms: Requesting a product through different compatibility dates will always return the same product but the data format might change. For example, an older version might not include the product's description, while another version might change some field's name from "title" to "product_name".
We made this decision to allow our data model to evolve and API users to make use of this without introducing a new API version every time.
REST endpoints and the overarching structure of webhook deliveries will never have any breaking changes under v2 but compatibility dates allow our datamodel to have such.
A compatibility date always follows the format YYYY-MM-DD
and should generally be set to the date you start working on your API integration.
Avoid picking dates in the past as documentation might not reflect older data models.
While theoretically possible, never pick compatibilty dates from the future as this might deliver data in a potentially unknown format, which is usually not what you want as breaking changes can be introduced any moment this way.
While the REST API and Webhooks handle setting/configuring the compatibility date differently, the data retrieved will always be in the same format for the same compatibility date, regardless of the interface it is accessed through.