Forge API Documentation
Forge has two APIs that allow our partners to run quests on our platform that reward players for their in-game activity.
One API for recording a player's game time
Another one is for recording a player's achievements in the game
Here are the in-game quests that are possible:
Play the game for N hours
Play the game for N days in a week
Play the game for N days in a row
Unlock a specific achievement in the game
Unlock N achievements in the game
Mapping “Partner game User with Forge Users”
Both the APIs accept either of the below as the unique identifier to map the “partner users” data with the corresponding “forge users”:
Email ID
Blockchain + Wallet Address
If a corresponding user is not present in “Forge,” the data will be archived immediately. It will be later used when a user joins Forge with an “Email ID”/”Blockchain + Wallet Address“ we have data already for or an existing Forge user who connects a new “Blockchain + Wallet Address” to forge for which we have data in the archive.
API Documentation
There are two APIs we support, one for playtime recording and another one for “achievements”:
Player Playtime Data ingestion API (
https://partners-api.forge.gg/player/playtime)Player Achievements Ingestion API (
https://partners-api.forge.gg/player/achievement)
API key
To access the Forge APIs, you will need an API key. Please reach out to the forge team directly to get an API key, as the “Key” creation process is currently manual.
Forge generates a unique API key for each partner integrating with our system. This key is used to identify the partner, game, and game_id. Also, there is a limit to how many requests one can make to our endpoint using an API Key. The current limit is set at 500K per day. It’s more of a soft/safety limit. If a game partner needs a higher limit, we can increase it.
The API Key format: it is a base64 encoding of
<partner-name>:<game-name>:<game-id>:<secret random-value of size: 12 characters>
Example: Game1,
game-name
game1
game-id
game1-01
random secret
cHq12EXeuZvP
The key will be like below.
APIs
Player Playtime Data Injection API
It’s an HTTP API to inject player game playtime activities to Forge. Partner and game details will be identified using the API key used in invoking the API. The API supports batch inserts as well to reduce the number of calls that’s been made to our service.
API Details
Method
POST
Rate Limited
Yes
Quota
Yes. Default: 500K requests per day.
Query Parameters
Not required
Headers
Content-Type
application/json
Payload Fields
last_time_played
datetime
✅
Format: YYYY-MM-DD HH:MI:SS
Session end time for the user playing the game in UTC
total_hours
float
✅
≥ 0
Total time played by the user for the current session.
user_email
string
**
Email address used by the user to connect to the game.
wallet_address
string
**
Any web3 wallet used by the user to connect to the game.
blockchain
string
**
Blockchain associated with the shared wallet address.
Note ** Either user_email or wallet_address is required. If wallet_address is used, blockchain in required.
Sample Invocation [Single Record]
An example that makes use of user’s email id to identify the user.
An example that makes use of user’s wallet_address to identify the user.
Sample Payload [Batch]
Our APIs support batch upload as well. Instead of sending in data 1 by 1, they can send it in as JSON array of records.
API Response
Status Code: 200
The API will return 200 if there is no errors
Status Code: 400
Errors in the payload format or data type or value
Status Code: 429
Reached the daily rate limit. Try again later.
Status Code: 401 or 403
If missing Authorization Headers missing or invalid
Status Code: 5XX
Our system down. Try again later.
Player Achievements Injection API
API to inject player’s in-game user achievements unlocked in the game. Partner and game details will be identified using the API key used in invoking the API. The API supports batch inserts as well to reduce the number of calls that’s been made to our service.
API Details
Method
POST
Rate Limited
Yes
Quota
Yes. Default: 500K requests per day.
Query Parameters
Not required
Headers
Content-Type
application/json
Payload Fields
achievement_title
string
✅
In game achievement name.
achievement_description
string
✅
A short description to describe the given achievement.
unlock_time
datetime
Format: YYYY-MM-DD HH:MI:SS
Timestamp at which the achievement is ‘achieved’ in game.
unlocked
boolean
✅
Indicator show the achievement is ‘achieved’ for the user.
user_email
string
**
Email address used by the user to connect to the game.
wallet_address
string
**
Any web3 wallet used by the user to connect to the game.
blockchain
string
**
Blockchain associated with the shared wallet address.
Note
** Either user_email or wallet_address is required. If wallet_address is used, blockchain in required.
Sample Invocation [Single Record]
An example that makes use of user’s email id to identify the user.
An example that makes use of user’s wallet_address to identify the user.
Sample Input Payload [Batch]
Our APIs support batch upload as well. Instead of sending in data 1 by 1, they can send it in as JSON array of records.
API Response
Status Code: 200
The API will return 200 if there is no errors
Status Code: 400
Errors in the payload format or data type or value
Status Code: 429
Reached the daily rate limit. Try again later.
Status Code: 401 or 403
If missing Authorization Headers missing or invalid
Status Code: 5XX
Our system down. Try again later.
Last updated