updates

Author: maanex

content/1.introduction/2.getting-started.md

@@ -1,14 +1,17 @@
 # Getting Started
 
-## API Key
+## Your application and credentials
 
-All requests to the API require authorization through an API key. To get your key visit https://dashboard.freestuffbot.xyz/ and click on **Your Application**. Create an application if not done already, then scroll down until you find your API key.
+To interact with any part of the FreeStuff API you need to create an application on https://dashboard.freestuffbot.xyz/.
+Once signed in you should find a button to view FreeStuff API settings on your home page.
+Go to Plans & Billing, then sign up for the free tier.
+
+If you choose to upgrade to a tier with REST API access you can find your API key under "Settings". This is also where your App's public key for webhook verification is located.
 
 
 ## Libraries
 
 There are libraries to interact with the API available for the following languages / ecosystems. Using such an API wrapper is the easiest way to interact with FreeStuff's API and we highly recommend using an existing API wrapper if one is available that fits your setup. Please refer to the libary's documentation for usage.
 
 - [Node / Bun (Official)](/libraries/node)
-- [Golang (Community Maintained)](/libraries/golang)
 

content/3.api-v2/2.concepts.md

@@ -57,10 +57,32 @@ More channels may be added in the future but here is our current list:
 :data-model{name="Channel"}
 
 
-## Summary
+## 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
+
+::alert{type="info"}
+If you are using a client library you do not need to worry about compatibility dates. Your library will handle all of this for you and use a version that it is compatible with.
+::
+
+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 other 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 possible, never pick compatibilty dates from the future as this always delivers data in the most up to date 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.

content/3.api-v2/3.usage-and-auth.md content/3.api-v2/3.rest-api.mdcontent/3.api-v2/3.usage-and-auth.md renamed to content/3.api-v2/3.rest-api.md

@@ -1,20 +1,27 @@
-# Usage & Auth
+# Rest API
 
 ::alert{type="info"}
 If you are on the free tier and do not have access to the REST Api you can skip this page.
 ::
 
-## Base Url
+## Base Url & Auth
 
 All endpoints are available on `https://api.freestuffbot.xyz/v2`
 
+You should already have an API key. If not please check out the [Getting Started](/introduction/getting-started) page.
 
-## Auth
+Your API key should be present in the `Authorization` header on every request to the API.
+Prefix your API key with the word `Basic`.
 
-You should already have an API key. If not please check out the [Getting Started](/introduction/getting-started) page.
+> Assuming your API key is "ABCDEFGHIJKLMNOPQRSTUVWXYZ", this is how your header should look like:\
+> `Authorization: Basic ABCDEFGHIJKLMNOPQRSTUVWXYZ`
+
+
+## List of endpoints
+
+:endpoint{name="get-ping"}
 
-Your API key should be present in the `Authorization` header on every request to the API. Prefix your API key with the word `Basic` as your access is of type basic.
+:endpoint{name="get-products"}
 
-So assuming your API key is "ABCDEFGHIJKLMNOPQRSTUVWXYZ", this is how your header should look like:
-`Authorization: Basic ABCDEFGHIJKLMNOPQRSTUVWXYZ`
+:endpoint{name="get-products-id"}
 

content/3.api-v2/4.endpoints.md

@@ -264,7 +264,7 @@
       ],
       "responses": [
         {
-          "code": 200,
+          "code": 204,
           "desc": "Success",
           "returns": {
             "body": "@",

content/3.api-v2/5.webhooks.md content/3.api-v2/4.webhooks.mdcontent/3.api-v2/5.webhooks.md renamed to content/3.api-v2/4.webhooks.md

@@ -1,6 +1,7 @@
 export default defineNuxtConfig({
   // https://github.com/nuxt-themes/docus
   extends: '@nuxt-themes/docus',
+
   // devtools: { enabled: true },
 
   typescript: {
@@ -10,9 +11,12 @@ export default defineNuxtConfig({
       }
     }
   },
+
   modules: [
     // Remove it if you don't use Plausible analytics
     // https://github.com/nuxt-modules/plausible
     // '@nuxtjs/plausible'
-  ]
-})
+  ],
+
+  compatibilityDate: '2025-05-05'
+})