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/
An empty GET request made to the top-level URL of your Battlesnake, used for customization, checking latency, and verifying successful communication between the Battlesnake and the Battlesnake Engine.
Request
Response
Request
Response
200: OK
example-battlesnake-customization.json
{
"apiversion": "1",
"author": "MyUsername",
"color" : "#888888",
"head" : "default",
"tail" : "default",
"version" : "0.0.1-beta"
}

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
/start

https://your.battlesnake.server.com/start
Your Battlesnake will receive this request when it has been entered into a new game. Every game has a unique ID that can be used to allocate resources or data you may need. Your response to this request will be ignored.
Request
Response
Request
Body Parameters
game
required
object
Game Object describing the game being played.
turn
required
integer
Turn number of the game being played (0 for new games).
board
required
object
Board Object describing the initial state of the game board.
you
required
object
Battlesnake Object describing your Battlesnake.
Response
200: OK
Responses to this command are ignored by the game engine.

Response Properties

Responses to this request are ignored by the game engine.

post
/move

https://your.battlesnake.server.com/move
This request will be sent for every turn of the game. Use the information provided to determine how your Battlesnake will move on that turn, either up, down, left, or right.
Request
Response
Request
Body Parameters
game
required
object
Game Object describing the game being played.
turn
required
integer
Turn number for this move.
board
required
object
Board Object describing the game board on this turn.
you
required
object
Battlesnake Object describing your Battlesnake.
Response
200: OK
application/json
{
"move": "up",
"shout": "I am moving up!"
}

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
/end

https://your.battlesnake.server.com/end
Your Battlesnake will receive this request whenever a game it was playing has ended. Use it to learn how your Battlesnake won or lost and deallocated any server-side resources. Your response to this request will be ignored.
Request
Response
Request
Body Parameters
game
required
object
Game Object describing the game being played.
turn
required
integer
Turn number for the last turn of this game.
board
required
object
Board Object describing the final turn of this game.
you
required
object
Battlesnake Object describing your Battlesnake.
Response
200: OK
Responses to this command are ignored by the game engine.

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
{
"id": "totally-unique-game-id",
"ruleset": {
"name": "standard",
"version": "v1.2.3"
},
"timeout": 500
}

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

Ruleset

example-ruleset-object.json
"ruleset": {
"name": "standard",
"version": "v1.2.3",
"settings": { ... }
}

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

example-ruleset-settings-object.json
"settings": {
"foodSpawnChance": 25,
"minimumFood": 1,
"hazardDamagePerTurn": 14,
"royale": {
"shrinkEveryNTurns": 5
},
"squad": {
"allowBodyCollisions": true,
"sharedElimination": true,
"sharedHealth": true,
"sharedLength": true
}
}

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
{
"id": "totally-unique-snake-id",
"name": "Sneky McSnek Face",
"health": 54,
"body": [
{"x": 0, "y": 0},
{"x": 1, "y": 0},
{"x": 2, "y": 0}
],
"latency": "123",
"head": {"x": 0, "y": 0},
"length": 3,
"shout": "why are we shouting??",
"squad": "1"
}

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
{
"height": 11,
"width": 11,
"food": [
{"x": 5, "y": 5},
{"x": 9, "y": 0},
{"x": 2, "y": 6}
],
"hazards": [
{"x": 0, "y": 0},
{"x": 0, "y": 1},
{"x": 0, "y": 2}
],
"snakes": [
{"id": "snake-one", ... },
{"id": "snake-two", ... },
{"id": "snake-three", ... }
]
}

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", ...}, ...]