Get Started

The GameNudge API is constructed as an REST-API with nouns and verbs.

The verbs availabe are the same as the representational states:

GET for retriving data
PUT for creating data
POST for altering data
DELETE for deleting data

The nouns used are "game", "player", "score", "leaderbord" and are described below.

Authentication

The only authentication needed to communicate with our API is your API-key. This can be found in your Account under Settings.

The API-key is passed in the header of your request as seen on the right.

Example of Authentication

curl -H "apikey:my_key" https://api.gamenudge.com/v1

Result

The current version of the API.

200

{"message":"API version is 1.0"}

Game

GET /game

Retrieves a list of all the games that is registered under your API-key.

Request

No additional parameters required.

Response

JSON-array where each item is a game as described below.

Field	Type	Value
id	String	The unique ID of your game. This value is used when retrieving a spcific game or when otherwise manipulating a specific game or its data.
name	String	The name that you have given your game.
num_players	Integer	The number of players currently active in your game.
players	Array	Array of all the players in your game

Endpoint

https://api.gamenudge.com/v1/game Result

List of games.

200


[
{
    "id":"JUpdHzoNPLi4ymAsYz3r4",
    "name":"My first game",
    "num_players":2,
    "players":[
    ]
},
{
    "id":"AhkwedLKHinkawasdewwe3",
    "name":"My second game",
    "num_players":3,
    "players":[
    ]
}
]

GET /game/[id]

Retrieves data on one specific game.

Request

No additonal parameters required.

Response

Field	Type	Value
id	String	The unique ID of your game. This value is used when retrieving a spcific game or when otherwise manipulating a specific game or its data.
name	String	The name that you have given your game.
num_players	Integer	The number of players currently active in your game.
players	Array	Array of all the players in your game

Endpoint

https://api.gamenudge.com/v1/game/JUpdHzoNPLi4ymAsYz3r4 Result

Data on the game requested.

200

                
                

{
    "id":"JUpdHzoNPLi4ymAsYz3r4",
    "name":"My first game",
    "num_players":1,
    "players":[
    ]
}

POST /game

Create a new game.

Request

Field	Type	Value
name	String	The name of your game. Does not need to be unique, but will be confusing if you hade multiple games with the same name.
maxscore	Integer	The max score of your game. Please be advised that the max score of your game may be limited by your type of account.
levels	Array	Key/value array where Key is the namn of the level and Value is the threshold to reach that level. 'Novice => 10' would create the level Novice and a player would reach that level when appointed 10 points.

Response

Field	Type	Value
id	String	The unique ID of your game. This value is used when retrieving a spcific game or when otherwise manipulating a specific game or its data.
name	String	The name that you have given your game.
num_players	Integer	The number of players currently active in your game.
players	Array	Array of all the players in your game

Endpoint

https://api.gamenudge.com/v1/game/ Result

Data on the game just created.

201

                
                

{
    "id":"JUpdHzoNPLi4ymAsYz3r4",
    "name":"My first game",
    "num_players":1,
    "players":[
    ]
}

DELETE /game/[id]

Delete a game. Just pass the game id in the URL

Endpoint

https://api.gamenudge.com/v1/game/[id] Result 200

Player

GET /player

Retrieves a list of all the players registered under your API-key.

Request

No additional parameters required.

Response

JSON-array where each item is a game as described below.

Field	Type	Value
name	String	The name of ypur player.
gn_id	String	The unique GameNudge ID given to the player.
player_id	String	The unique player id that you assigned to the player when creating it.

Endpoint

https://api.gamenudge.com/v1/player Result 200


[
    {
        "name":"Player One",
        "gn_id":"WPZ6MeasdwdasjNXvfwn9jgg",
        "player_id":"player.one@mydomain.site"
    },
    {
        "name":"Player Two",
        "gn_id":"WPZ6MeasdwdasjNXvfwasdasa",
        "player_id":"player.two@mydomain.site"
    }
]

GET /player/[id]

Retrieves data on a specific player.

Request

Add the your unique player id to the URL.

Response

JSON-array where each item is a game as described below.

Field	Type	Value
name	String	The name of ypur player.
gn_id	String	The unique GameNudge ID given to the player.
player_id	String	The unique player id that you assigned to the player when creating it.
Games	Array	Array with the unique game ids of all the games the player is participating in.

Endpoint

https://api.gamenudge.com/v1/player Result 200


{
    "name":"Player One",
    "gn_id":"WPZ6MeasdwdasjNXvfwn9jgg",
    "player_id":"player.one@mydomain.site",
    "games":["JUpdHzoLYRNPLi4yJ8HkY"]
}

PUT /player

Edit a new player. Not in beta.

Request

Response

Endpoint

POST /player

Create a new player.

Request

Field	Type	Value
name	String	The name of your player. Does not need to be unique, but will be confusing if you hade multiple players with the same name.
uid	string	A unique identifer of your player, typically an e-mail address.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/player Result 201

DELETE /player/[id]

Delete a player. Just pass the player id in the URL

Endpoint

https://api.gamenudge.com/v1/player/[id] Result 200

Participate

PUT /participate

Add a player to a game.

Request

Field	Type	Value
player_uid	String	The unique identifer of your player.
game_uid	string	The unique identifer of your game.
game_name	string	The name of the game.
player_gn_id	string	The unique GameNudge generated string that identifies your player.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/participate Result 201

DELETE /participate

Remove a player from a game.

Request

Field	Type	Value
player_uid	String	The unique identifer of your player.
game_uid	string	The unique identifer of your game.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/participate Result 200

Score

PUT /score

Add points to a player in a game.

Request

Field	Type	Value
player_uid	String	The unique identifer of your player.
game_uid	string	The unique identifer of your game.
points	number	The number of points to be added.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/score Result

The current score after the new score has been added.

200

Career

GET /career/[id]

Get all the game stats on a player.

Request

Field	Type	Value
id	String in the query	The unique identifer of your player.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/participate Result 200

Leaderboard

GET /leaderboard/[id]

Get the leaderboard of a game.

Request

Field	Type	Value
id	String in the query	The unique identifer of your game.

Response

HTTP status code.

Endpoint

https://api.gamenudge.com/v1/leaderboard Result 200

Codes

200 OK

You request has been executed as planned. This is usually returned from GET, POST, and DELETE request.

201 Created

You have created for example a game or player. Note that adding scores to a player in a game does not return a 201 as the players score is nor created (PUT) but updated (POST) from one value to another (zero to something the first time) and therefore returns a 200.

400 Bad Request

Your request could not be executed due to wrong or insufficient input data from your end. Correct and try again.

50X

Well. Something is really wrong. And this one is on us.