API Reference

Official Reference for the Battlesnake API (Version 1)

Introduction

The Battlesnake API is an inverted HTTP API. 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.

The Battlesnake API

Your Battlesnake server must implement the following HTTP calls to play the game.

get
/

https://your.battlesnake.server.com/
This request will be made periodically to retrieve information about your Battlesnake, including its display options, author, etc.
Request
Response
Request
Response
200: OK
application/json
{
"apiversion": "1",
"author": "your-username",
"color": "#888888",
"head": "default",
"tail": "default"
}

Response Properties

Parameter

Type

Description

apiversion

string

Version of the Battlesnake API implemented by this Battlesnake. 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"

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
optional
object
Game Object describing the game being played.
turn
optional
integer
Turn number of the game being played (0 for new games).
board
optional
object
Board Object describing the initial state of the game board.
you
optional
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
optional
object
Game Object describing the game being played.
turn
optional
integer
Turn number for this move.
board
optional
object
Board Object describing the game board on this turn.
you
optional
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
optional
object
Game Object describing the game being played.
turn
optional
integer
Turn number for the last turn of this game.
board
optional
object
Board Object describing the final turn of this game.
you
optional
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",
"timeout": 500
}

Property

Type

Description

id

string

A unique identifier for this Game.

Example: "totally-unique-game-id"

timeout

integer (milliseconds)

How much time your snake has to respond to requests for this Game.

Example: 500

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}
],
"head": {"x": 0, "y": 0},
"length": 3,
"shout": "why are we shouting??"
}

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}]

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??"

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 12x12 will have coordinates ranging from [0, 11].

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

Height of the game board.

Example: 11

width

integer

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

Example Move Request

Here's a complete example of a request made to POST /move and a valid Battlesnake response to move up.

Request

POST https://your.battlesnake.server.com/move
{
"game": {
"id": "game-00fe20da-94ad-11ea-bb37",
"timeout": 500
},
"turn": 14,
"board": {
"height": 11,
"width": 11,
"food": [
{"x": 5, "y": 5},
{"x": 9, "y": 0},
{"x": 2, "y": 6}
],
"hazards": [
{"x": 0, "y": 0}
],
"snakes": [
{
"id": "snake-508e96ac-94ad-11ea-bb37",
"name": "My Snake",
"health": 54,
"body": [
{"x": 0, "y": 0},
{"x": 1, "y": 0},
{"x": 2, "y": 0}
],
"head": {"x": 0, "y": 0},
"length": 3,
"shout": "why are we shouting??"
},
{
"id": "snake-b67f4906-94ae-11ea-bb37",
"name": "Another Snake",
"health": 16,
"body": [
{"x": 5, "y": 4},
{"x": 5, "y": 3},
{"x": 6, "y": 3},
{"x": 6, "y": 2}
],
"head": {"x": 5, "y": 4},
"length": 4,
"shout": "I'm not really sure..."
}
]
},
"you": {
"id": "snake-508e96ac-94ad-11ea-bb37",
"name": "My Snake",
"health": 54,
"body": [
{"x": 0, "y": 0},
{"x": 1, "y": 0},
{"x": 2, "y": 0}
],
"head": {"x": 0, "y": 0},
"length": 3,
"shout": "why are we shouting??"
}
}

Response

200 OK
{
"move": "up",
"shout": "I guess I'll go up then."
}