API Reference
Official Reference for the Battlesnake API, Version 1

Introduction

The Battlesnake API is an HTTP Webhook API, meaning developers build a web server that implements this API and the game engine will act as an API client during each game. How your server responds to these requests controls how your Battlesnake behaves.
Requests sent to your Battlesnake will be JSON-encoded, using standard HTTP request methods and content types.

HTTP Response Codes

All Battlesnake API requests must return a valid HTTP `200 OK`. If any other status code is returned, the game engine will consider it an error and act accordingly.

Response Content-Type

All responses must be JSON-encoded strings sent as `application/json`. If the game engine receives an invalid response from your Battlesnake it will consider it an error and act accordingly.

Request Timeouts

Every request made to your Battlesnake server must be responded to within the given timeout value. In most standard games this will be 500ms, however, this value can vary from game to game. Use the game information provided in the request to determine how long your Battlesnake should spend computing its next move.
Note that these values include round-trip latency, so communication between the game engine and your Battlesnake server should be taken into consideration.
In the event of a request timeout, the Battlesnake engine will repeat the last move received from your Battlesnake. For example, if your Battlesnake's previous move was 'right', and the next request times out, the Battlesnake Engine will continue to move your Battlesnake to the 'right'.

The Battlesnake API

The Battlesnake API consists of four commands. Your Battlesnake server must implement all four HTTP calls to play the game. These commands are called at different times during each game and your response to these command controls how your Battlesnake appears and behaves on the game board.
Command: Get Battlesnake This command is called periodically by the game engine and the Battlesnake platform. It should return information about your Battlesnake, including who created it and what it looks like.
Command: Start Game This command is called once at the beginning of every game to let your Battlesnake know that a new game is about to start.
Command: Move This command is called once per turn of each game, providing information about the game board to your Battlesnake and asking for its next move. Your response to this command determines how your Battlesnake behaves and will be the primary focus of your game logic programming.
Command: End Game This command is called once after each game has been completed to let your Battlesnake know that the game is over.
get
https://your.battlesnake.server.com
/
/
1
example-battlesnake-customization.json
2
3
{
4
"apiversion": "1",
5
"author": "MyUsername",
6
"color" : "#888888",
7
"head" : "default",
8
"tail" : "default",
9
"version" : "0.0.1-beta"
10
}
Copied!
Response Properties
Parameter
Type
Description
apiversion
string (required)
Version of the Battlesnake API implemented by this Battlesnake. Currently only API version 1 is valid. Example: "1"
author
string (optional)
Username of the author of this Battlesnake. If provided, this will be used to verify ownership.
Example: "BattlesnakeOfficial"
color
string (optional)
Hex color code used to display this Battlesnake. Must start with "#" and be 7 characters long.
Example: "#888888"
head
string (optional)
Displayed head of this Battlesnake. See Personalization Docs for available options
Example: "default"
tail
string (optional)
Displayed tail of this Battlesnake. See Personalization Docs for available options.
Example: "default"
version
string (optional)
A version number or tag for your snake.
See Personalization Reference for available colors, heads, and tails.
post
https://your.battlesnake.server.com
/start
/start
Response Properties
Responses to this request are ignored by the game engine.
post
https://your.battlesnake.server.com
/move
/move
Response Properties
Parameter
Type
Description
move
string
Your Battlesnake's move for this turn. Valid moves are up, down, left, or right.
Example: "up"
shout
string (optional)
An optional message sent to all other Battlesnakes on the next turn. Must be 256 characters or less.
Example: "I am moving up!"
post
https://your.battlesnake.server.com
/end
/end
Response Properties
Responses to this request are ignored by the game engine.

Object Definitions

The Battlesnake API uses the following object definitions when communicating with your Battlesnake web server.

Game

example-game-object.json
1
{
2
"id": "totally-unique-game-id",
3
"ruleset": {
4
"name": "standard",
5
"version": "v1.2.3"
6
},
7
"timeout": 500,
8
"source": "league"
9
}
Copied!
Property
Type
Description
id
string
A unique identifier for this Game.
Example: "totally-unique-game-id"
ruleset
object
Information about the ruleset being used to run this game.
Example: {"name": "standard", "version": "v1.2.3"}
timeout
integer (milliseconds)
How much time your snake has to respond to requests for this Game.
Example: 500
source
string
The source of this game, e.g. "league" or "custom".
The values for this field may change in the near future.

Ruleset

1
example-ruleset-object.json
2
3
"ruleset": {
4
"name": "standard",
5
"version": "v1.2.3",
6
"settings": { ... }
7
}
8
Copied!
Property
Type
Description
name
string
Name of the ruleset being used to run this game. Possible values include: standard, solo, royale, squad, constrictor. See Game Modes for more information on each ruleset.
Example: "standard"
version
string
The release version of the Rules module used in this game.
Example: "version": "v1.2.3"
settings
object
A collection of specific settings being used by the current game that control how the rules are applied.

RulesetSettings

1
example-ruleset-settings-object.json
2
3
"settings": {
4
"foodSpawnChance": 25,
5
"minimumFood": 1,
6
"hazardDamagePerTurn": 14,
7
"royale": {
8
"shrinkEveryNTurns": 5
9
},
10
"squad": {
11
"allowBodyCollisions": true,
12
"sharedElimination": true,
13
"sharedHealth": true,
14
"sharedLength": true
15
}
16
}
Copied!
All ruleset settings will always be passed, but ruleset-specific settings (e.g. under royale, squad) will only take effect when the associated ruleset is in effect. For example, in a standard game, the value for royale.shrinkEveryNTurns isn't used in the game rules, but your Battlesnake server can still read it.
Property
Type
Description
foodSpawnChance
integer
Percentage chance of spawning a new food every round.
minimumFood
integer
Minimum food to keep on the board every turn.
hazardDamagePerTurn
integer
Health damage a snake will take when ending its turn in a hazard. This stacks on top of the regular 1 damage a snake takes per turn.
royale.shrinkEveryNTurns
integer
In Royale mode, the number of turns between generating new hazards (shrinking the safe board space).
squad.allowBodyCollisions
boolean
In Squad mode, allow members of the same squad to move over each other without dying.
squad.sharedElimination
boolean
In Squad mode, all squad members are eliminated when one is eliminated.
squad.sharedHealth
boolean
In Squad mode, all squad members share health.
squad.sharedLength
boolean
In Squad mode, all squad members share length.

Battlesnake

example-battlesnake-object.json
1
{
2
"id": "totally-unique-snake-id",
3
"name": "Sneky McSnek Face",
4
"health": 54,
5
"body": [
6
{"x": 0, "y": 0},
7
{"x": 1, "y": 0},
8
{"x": 2, "y": 0}
9
],
10
"latency": "123",
11
"head": {"x": 0, "y": 0},
12
"length": 3,
13
"shout": "why are we shouting??",
14
"squad": "1"
15
}
Copied!
Property
Type
Description
id
string
Unique identifier for this Battlesnake in the context of the current Game.
Example: "totally-unique-snake-id"
name
string
Name given to this Battlesnake by its author.
Example: "Sneky McSnek Face"
health
integer
Health value of this Battlesnake, between 0 and 100 inclusively.
Example: 54
body
array
Array of coordinates representing this Battlesnake's location on the game board. This array is ordered from head to tail.
Example: [{"x": 0, "y": 0}, ..., {"x": 2, "y": 0}]
latency
string
The previous response time of this Battlesnake, in milliseconds. "0" means the Battlesnake timed out and failed to respond.
Example: "450"
head
object
Coordinates for this Battlesnake's head. Equivalent to the first element of the body array.
Example: {"x": 0, "y": 0}
length
integer
Length of this Battlesnake from head to tail. Equivalent to the length of the body array.
Example: 3
shout
string
Message shouted by this Battlesnake on the previous turn.
Example: "why are we shouting??"
squad
string
The squad that the Battlesnake belongs to. Used to identify squad members in Squad Mode games.
Example: "1"

Board

The game board is represented by a standard 2D grid, oriented with (0,0) in the bottom left. The Y-Axis is positive in the up direction, and X-Axis is positive to the right. Coordinates begin at zero, such that a board that is 11x11 will have coordinates ranging from [0, 10].
Battlesnake Coordinate System
example-board-object.json
1
{
2
"height": 11,
3
"width": 11,
4
"food": [
5
{"x": 5, "y": 5},
6
{"x": 9, "y": 0},
7
{"x": 2, "y": 6}
8
],
9
"hazards": [
10
{"x": 0, "y": 0},
11
{"x": 0, "y": 1},
12
{"x": 0, "y": 2}
13
],
14
"snakes": [
15
{"id": "snake-one", ... },
16
{"id": "snake-two", ... },
17
{"id": "snake-three", ... }
18
]
19
}
Copied!
Property
Type
Description
height
integer
The number of rows in the y-axis of the game board.
Example: 11
width
integer
The number of columns in the x-axis of the game board.
Example: 11
food
array
Array of coordinates representing food locations on the game board.
Example: [{"x": 5, "y": 5}, ..., {"x": 2, "y": 6}]
hazards
array
Array of coordinates representing hazardous locations on the game board. These will only appear in some game modes.
Example: [{"x": 0, "y": 0}, ..., {"x": 0, "y": 1}]
snakes
array
Array of Battlesnake Objects representing all Battlesnakes remaining on the game board (including yourself if you haven't been eliminated).
Example: [{"id": "snake-one", ...}, ...]
Last modified 3d ago