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:
get
Ping
https://api.freestuffbot.xyz/v1/ping
Pings the api
Rate-Limits: none
Request
Response
Request
Headers
Authorization
required
string
Authentication token
Response
200: OK
Cake successfully retrieved.
{
    "success": true,
    "data": { }
}
get
Game List
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
Request
Response
Request
Path Parameters
category
required
string
The requested category. See above for more info.
Headers
Authorization
required
string
Authentication token
Response
200: OK
See Type Definitions for more info.
{
    "success": true,
    "data": [
        12345,
        67890
    ]
}
​
X-Meta-LastUpdate=<updateTimestamp>
502: Bad Gateway
Connection to database failed.
{
    "success": false,
    "error": "Bad Gateway",
    "message": "Database not available",
    "data": [ ]
}
get
Game Details
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
Request
Response
Request
Path Parameters
lookup
required
string
Define what data you want to get. See above for more info.
id
required
string
The game's id. You may request up to 5 games in one call by chaining the ids using the + character.
Headers
Authorization
required
string
Authentication token
Query Parameters
lang
optional
string
Request localized versions of the game info. Chain multiple languages using the + character.
Response
200: OK
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:
post
Game Announcement Analytic Data
https://api.freestuffbot.xyz/v1/game/:id/analytics
Send once after finishing an announcement to report your analytical data.
Request
Response
Request
Path Parameters
id
required
string
game's id
Headers
Authorization
required
string
Authorization token
Body Parameters
data
required
string
Your data in the same model as stored in the database. Varies by service kind.
suid
required
string
service unique id
service
required
string
"discord" | "telegram"
Response
200: OK
{
    "success": true
}
Introduction
Next - v1
Webhooks & Events
Last updated 3 days ago
Endpoints

Public Access Endpoints:

getPing

getGame List

getGame Details

Restricted Access Endpoints:

postGame Announcement Analytic Data

get
Ping

get
Game List

get
Game Details

post
Game Announcement Analytic Data
