FreeStuff API

https://docs.freestuffbot.xyz
Admin
FreeStuff provides real-time data and notifications about free games, discounts, in-game content,...
Tokens:8,925
Snippets:72
Trust Score:7.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install FreeStuff with Bun

Source: https://docs.freestuffbot.xyz/libraries/node

Use `bun add freestuff` to install the official FreeStuff API package in a Bun project.

```bash
bun add freestuff
```

--------------------------------

### Install FreeStuff with NPM

Source: https://docs.freestuffbot.xyz/libraries/node

Use `npm install freestuff` to install the official FreeStuff API package in an NPM project.

```bash
npm install freestuff
```

--------------------------------

### Install FreeStuff with Yarn

Source: https://docs.freestuffbot.xyz/libraries/node

Use `yarn add freestuff` to install the official FreeStuff API package in a Yarn project.

```bash
yarn add freestuff
```

--------------------------------

### GET /products

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Lists products with optional filtering and pagination. Requires a Bearer token and full tier access.

```APIDOC
## GET /products

### Description
Lists products with optional filtering and pagination. Requires a Bearer token and full tier access.

### Method
GET

### Endpoint
/products

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token
- **If-None-Match** (string) - Optional - A previously received ETag value. Recommended but not required.

#### Query Parameters
- **limit** (integer) - Optional - Limit how many products are returned at once
- **offset** (integer) - Optional - Offset the results. Used with limit parameter for pagination.
- **resolve** (boolean) - Optional - If set to true will return full products instead of partial ones. The ETag hash will also be computed over the entire product data and not just their ids.
- **type** (Channel) - Optional - Filter: Only list products with the given type
- **kind** (ProductKind) - Optional - Filter: Only list products with the given kind
- **store** (ProductStore) - Optional - Filter: Only list products with the given store

### Response
#### Success Response (200)
- **products** (array) - List of PartialProduct objects
  - **id** (integer) - Product ID
  - **kind** (string) - Product kind
  - **until** (integer) - Until timestamp
  - **type** (string) - Product type
  - **flags** (integer) - Flags
  - **store** (string) - Store identifier
- **count** (integer) - Total number of results

#### Response Example
{
  "products": [
    {
      "id": 123456,
      "kind": "game",
      "until": 0,
      "type": "keep",
      "flags": 0,
      "store": "steam"
    }
  ],
  "count": 1
}

#### Error Response (400)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message

#### Error Response (404)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message
```

--------------------------------

### GET /static/schemas

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Retrieves a list of available schemas. Requires a Bearer token.

```APIDOC
## GET /static/schemas

### Description
Retrieves a list of available schemas.

### Method
GET

### Endpoint
/static/schemas

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token

### Response
#### Success Response (200)
- **type** (string) - The response type identifier
- **list** (array) - List of schema objects
  - **name** (string) - Schema name
  - **urn** (string) - Schema URN
  - **active** (boolean) - Whether the schema is active
  - **latestVersion** (string) - Latest version of the schema

#### Response Example
{
  "type": "fsb:static:apiv2:schema_list",
  "list": [
    {
      "name": "Product",
      "urn": "fsb:schema:apiv2:product",
      "active": true,
      "latestVersion": "9999-99-99"
    }
  ]
}
```

--------------------------------

### GET /static/problems

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Retrieves a list of problem types. Requires a Bearer token.

```APIDOC
## GET /static/problems

### Description
Retrieves a list of problem types.

### Method
GET

### Endpoint
/static/problems

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token

### Response
#### Success Response (200)
- **type** (string) - The response type identifier
- **list** (array) - List of problem objects
  - **urn** (string) - Problem URN
  - **status** (integer) - HTTP status code
  - **title** (string) - Error title

#### Response Example
{
  "type": "fsb:static:apiv2:problem_list",
  "list": [
    {
      "urn": "fsb:problem:example",
      "status": 400,
      "title": "Example error"
    }
  ]
}
```

--------------------------------

### GET /products/{id}

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Retrieves a single product by its ID. Requires a Bearer token and full tier access.

```APIDOC
## GET /products/{id}

### Description
Retrieves a single product by its ID. Requires a Bearer token and full tier access.

### Method
GET

### Endpoint
/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The id of the product you're looking up

#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token
- **If-None-Match** (string) - Optional - A previously received ETag value. Recommended but not required.

### Response
#### Success Response (200)
- **TODO** (boolean) - Placeholder field

#### Response Example
{
  "TODO": true
}

#### Error Response (400)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message

#### Error Response (404)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message

#### Error Response (502)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message
```

--------------------------------

### GET /static/schemas/{urn}

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Retrieves a specific schema by its URN. Requires a Bearer token.

```APIDOC
## GET /static/schemas/{urn}

### Description
Retrieves a specific schema by its URN.

### Method
GET

### Endpoint
/static/schemas/{urn}

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token

### Response
#### Success Response (200)
- **type** (string) - The response type identifier
- **schema** (object) - The schema object

#### Response Example
{
  "type": "fsb:static:apiv2:schema",
  "schema": {
    "type": "object",
    "properties": {}
  }
}

#### Error Response (404)
- **type** (string) - Problem type identifier
- **title** (string) - Error title
- **detail** (string) - Error message

#### Error Response Example
{
  "type": "fsb:problem:name-here",
  "title": "error name",
  "detail": "error message"
}
```

--------------------------------

### GET /static/events

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

Retrieves a list of event types. Requires a Bearer token.

```APIDOC
## GET /static/events

### Description
Retrieves a list of event types.

### Method
GET

### Endpoint
/static/events

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Your Bearer token

### Response
#### Success Response (200)
- **type** (string) - The response type identifier
- **list** (array) - List of event objects
  - **urn** (string) - Event URN
  - **description** (string) - Human readable description of the event
  - **payloadDescription** (string) - Human readable description of the event payload
  - **payloadSchema** (object) - JSON schema of the event payload

#### Response Example
{
  "type": "fsb:static:apiv2:event_list",
  "list": [
    {
      "urn": "fsb:event:example",
      "description": "Human readable description of the event",
      "payloadDescription": "Human readable description of the event payload",
      "payloadSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}
```

--------------------------------

### Webhook Message Payload Example

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Example of the HTTP body sent by FreeStuff webhooks, following the Standard Webhooks Spec. The 'type' field indicates the event type, 'timestamp' is the event time, and 'data' contains the event-specific payload.

```json
{
  "type": "fsb:event:announcement_created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    // ...
  }
}
```

--------------------------------

### Webhook Delivery Response

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Guidelines for responding to webhook requests from FreeStuff, including required status codes and optional headers.

```APIDOC
## Webhook Delivery Response

### Description
Respond to a webhook delivery from FreeStuff with a 2xx status code to acknowledge successful receipt. Optionally include headers to set compatibility date or identify your client library.

### Method
POST (implied by webhook delivery)

### Endpoint
(Webhook URL configured by the user)

### Parameters
#### Request Headers
- **X-Compatibility-Date** (string) - Optional - The compatibility date of the request payload. If unexpected, you may respond with a 4xx to trigger a resend with the correct date.

#### Response Headers
- **X-Set-Compatibility-Date** (string) - Optional - A valid compatibility date to overwrite the app's compatibility date for future deliveries.
- **X-Client-Library** (string) - Optional - Format: `Library Name/version (url)` e.g., `FreeStuff.py/1.0.2 (https://github.com/my/fake-repo)`.

### Response
#### Success Response (204 No Content)
- Empty body is preferred.
- Any 2xx status code is accepted.

#### Error Response (4xx)
- Use a 4xx status code if the `X-Compatibility-Date` header is incompatible, to force a resend with the correct date.

### Notes
- Failure to process data should still return 2xx, as delivery is considered successful.
- Consecutive failures (no 2xx) over multiple days may result in webhook removal.
- Resend timing may differ from the Standard Webhooks Spec.
```

--------------------------------

### fsb:event:product_updated

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Fired when a previously published product is updated. The data field contains the full Product data, not just the changes.

```APIDOC
## Event: fsb:event:product_updated

### Description
Fired when a previously published product is updated.

### Data Payload
The `data` field will contain the **full** `Product` data, not just the changes.

```
{
  id: int
  title: string
  prices: ProductPrice[]
  kind: ProductKind
  tags: string[] // unsorted, non-standardized, human readable
  images: ProductImage[] // *this array will only have a subset of all available images on the free tier
  description: string // human readable description in english language
  rating: float // this is an aggregated score where 0 represents the worst possible and 1 the best possible rating
  copyright: string // name of the ip copyright holder
  until: int // unix timestamp in ms
  type: Channel
  urls: ProductUrl[] // *this array will only have a subset of all available urls on the free tier
  store: Store // steam, epic games, etc.
  flags: ProductFlags
  notice: string // a rare optional extra info text added by a FreeStuff team member meant for public display alongside the product
  staffApproved: boolean // true means a human checked the data prior to being published
  *platforms: Platform[] // *this array will always be empty on the free tier
  *meta: ProductMeta[] // *this array will always be empty on the free tier
}
```
```

--------------------------------

### Authentication

Source: https://docs.freestuffbot.xyz/api-v2/rest-api

All API requests require an API key. The key must be included in the Authorization header with the Bearer prefix.

```APIDOC
## Authentication

### Description
All endpoints require an API key. The API key must be sent in the Authorization header with the Bearer prefix.

### Header
- **Authorization** (string) - Required - Format: `Bearer <API_KEY>`

### Example
`Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ`
```

--------------------------------

### fsb:event:announcement_created

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Fired when a new announcement is published. The data field contains a single ResolvedAnnouncement object, with a resolvedProducts field listing all new products.

```APIDOC
## Event: fsb:event:announcement_created

### Description
Fired when a new announcement is published.

### Data Payload
The `data` field will contain a single `ResolvedAnnouncement`. Check its `resolvedProducts` field for a list of all new products.

```
{
  id: number
  products: int[] // ids of all products in the announcement
  resolvedProducts: Product[] // resolved products
}
```
```

--------------------------------

### fsb:event:announcement_created data payload

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Payload for the announcement_created event. Contains a ResolvedAnnouncement with a list of new products.

```json
{
id: number
products: int[]— ids of all products in the announcement
resolvedProducts: Product[]— resolved products
}
```

--------------------------------

### fsb:event:product_updated data payload

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Payload for the product_updated event. Contains the full Product data, not just changes. Note that some fields are limited on the free tier.

```json
{
id: int
title: string
prices: ProductPrice[]
kind: ProductKind
tags: string[]— unsorted, non-standardized, human readable
images: ProductImage[]— *this array will only have a subset of all available images on the free tier
description: string— human readable description in english language
rating: float— this is an aggregated score where 0 represents the worst possible and 1 the best possible rating
copyright: string— name of the ip copyright holder
until: int— unix timestamp in ms
type: Channel
urls: ProductUrl[]— *this array will only have a subset of all available urls on the free tier
store: Store— steam, epic games, etc.
flags: ProductFlags
notice: string— a rare optional extra info text added by a FreeStuff team member meant for public display alongside the product
staffApproved: boolean— true means a human checked the data prior to being published
*platforms: Platform[]— *this array will always be empty on the free tier
*meta: ProductMeta[]— *this array will always be empty on the free tier
}
```

--------------------------------

### fsb:event:ping

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Fired when the ping button is pressed on your dashboard or periodically to check if your webhook is still operational. The data field contains an object with a manual boolean flag.

```APIDOC
## Event: fsb:event:ping

### Description
Fired either when the ping button was pressed on your dashboard or periodically to check if your webhook is still operational.

### Data Payload
The `data` field will contain the following object:

```
{
  "manual": boolean // will be true if you manually requested this ping, false otherwise
}
```
```

--------------------------------

### fsb:event:ping data payload

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

Payload for the ping event. The 'manual' field indicates whether the ping was manually requested.

```json
{
  "manual": boolean // will be true if you manually requested this ping, false otherwise
}
```

--------------------------------

### Webhook Message Payload

Source: https://docs.freestuffbot.xyz/api-v2/webhooks

The HTTP body of a webhook request follows the Standard Webhooks Spec and contains a type, timestamp, and data field.

```APIDOC
## Webhook Message Payload

### Description
The message payload (HTTP body) follows the Standard Webhooks Spec and contains the event type, timestamp, and data.

### Method
POST

### Endpoint
[Your configured webhook URL]

### Request Body
- **type** (string) - Required - The event type, e.g., `fsb:event:announcement_created`.
- **timestamp** (string) - Required - The ISO 8601 timestamp of the event.
- **data** (object) - Required - The event-specific data.

### Request Example
```json
{
  "type": "fsb:event:announcement_created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    // ...
  }
}
```

### Headers
- **X-Compatibility-Date** - The compatibility date of the content in the payload's data field.
- **Webhook-Id** - The message ID, used for verification.
- **Webhook-Timestamp** - The message send timestamp, used for verification.
- **Webhook-Signature** - The message signature, used for verification.

### Verification
To verify the request, use your Ed25519 public key (found on your app page). The content to verify is `msg_id.timestamp.payload`, where `msg_id` and `timestamp` are from the `Webhook-Id` and `Webhook-Timestamp` headers, and `payload` is the raw HTTP body. Store `msg_id` to prevent replay attacks, and ignore requests with old `Webhook-Timestamp` values. The timestamp uses a custom epoch of `2025-01-01` and precision of seconds; to get current time, multiply the header value by 1000 and add 1735689600000. Use the payload body `timestamp` field as the contextual timestamp.
```
Tokens:
Raw