Endpoints

API Endpoints

All endpoints require authorization. Please read the introduction page for more information.

All successful responses are served in the following format with status 200:

{
    "success": true,
    "data": { ... }
}

All non-successful responses are served in the following format with status other than 200:

{
    "success": false,
    "error": "Error Name",
    "message": "Detailed Description"
}

(Format might vary on restricted access endpoints)

All responses contain the following response headers in addition to the endpoint specific response headers:

X-Server-Time=<timestamp UNIX> The server's timestamp of receiving the request.

X-RateLimit-Limit=<number> The max amount of requests to this endpoint per interval

X-RateLimit-Remaining=<number> The amount of remaining requests to this endpoint

X-RateLimit-Reset=<timestamp UNIX/1000> End of current interval

Retry-After=<number> Optional, only if rate-limited. The amount of seconds to wait before another request to this endpoint.

Public Access Endpoints:

Ping

GET https://api.freestuffbot.xyz/v1/ping

Pings the api Rate-Limits: none

Headers

Name	Type	Description
Authorization	string	Authentication token

200 Cake successfully retrieved.

{
    "success": true,
    "data": { }
}

Game List

GET https://api.freestuffbot.xyz/v1/games/:category

Returns an integer array with the ids of all games in the requested category. The following categories are available: all will list all games in the database approved will list all games in the database that have been manually approved by our content moderators free will list all games currently free Rate-Limits: 5x in 15min

Path Parameters

Name	Type	Description
category	string	The requested category. See above for more info.

Headers

Name	Type	Description
Authorization	string	Authentication token

200 See Type Definitions for more info.

{
    "success": true,
    "data": [
        12345,
        67890
    ]
}

X-Meta-LastUpdate=<updateTimestamp>

502 Connection to database failed.

{
    "success": false,
    "error": "Bad Gateway",
    "message": "Database not available",
    "data": [ ]
}

Game Details

GET https://api.freestuffbot.xyz/v1/game/:id/:lookup

Get information about a game by looking up it's id. Define what data you want to get using the lookup parameter: Public Access: info will return basic information about the game. Partner Only: analytics will return all analytical data stored about the game. all will return all information about the game, including content moderation metadata. The returned data might vary from the information described in the documentation. Please query the endpoint with example data to get an actual reference object. Rate-Limits: 10x in 5 min

Path Parameters

Name	Type	Description
lookup	string	Define what data you want to get. See above for more info.
id	string	The game's id. You may request up to 5 games in one call by chaining the ids using the + character.

Query Parameters

Name	Type	Description
lang	string	Request localized versions of the game info. Chain multiple languages using the + character.

Headers

Name	Type	Description
Authorization	string	Authentication token

200 Example response with :id=1234+5678 and :lookup=info, where 1234 is a valid id and 5678 is not.

{
    "success": true,
    "data": {
        "1234": @GameInfo,
        "5678": null
    }
}

Restricted Access Endpoints:

Game Announcement Analytic Data

POST https://api.freestuffbot.xyz/v1/game/:id/analytics

Send once after finishing an announcement to report your analytical data.

Path Parameters

Name	Type	Description
id	string	game's id

Headers

Name	Type	Description
Authorization	string	Authorization token

Request Body

Name	Type	Description
data	string	Your data in the same model as stored in the database. Varies by service kind.
suid	string	service unique id
service	string	"discord" | "telegram"

200

{
    "success": true
}