api

description
Official Reference for the Battlesnake API, Version 1

API Reference

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.com/

An empty GET request made to the top-level URL of your Battlesnake, used for customization, checking latency, and verifying successful communications between the Battlesnake and the Battlesnake Engine.

Parameters

Responses	Type
🟢 200	application/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.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 allocated resources or data you may need. Your response to this request will be ignored.

Parameters

Body	Type	Description
game	object	Game Object describing the game being played.
turn	integer	Turn number of the game being played (0 for new games).
board	object	Board Object describing the initial state of the game board.
you	object	Battlesnake Object describing your Battlesnake.

Responses	Type
🟢 200	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.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.

Parameters

Body	Type	Description
game	object	Game Object describing the game being played.
turn	integer	Turn number for this move.
board	object	Board Object describing the game board on this turn.
you	object	Battlesnake Object describing your Battlesnake.

Responses	Type
🟢 200	application/json

{
  "move": "up",
  "shout": "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.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 deallocate any server-side resources. Your response to this request will be ignored.

Parameters

Body	Type	Description
game	object	Game Object describing the game being played.
turn	integer	Turn number for the last turn of the game.
board	object	Board Object describing the final state of the game board.
you	object	Battlesnake Object describing your Battlesnake.

Responses	Type
🟢 200	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

{% code title="example-game-object.json" %}

{
  "id": "totally-unique-game-id",
  "ruleset": {
    "name": "standard",
    "version": "v1.2.3"
  },
  "map": "standard",
  "timeout": 500,
  "source": "league"
}

{% endcode %}

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"}
map	string	The name of the map used to populate the game board with snakes, food, and hazards. Example: "standard" See Game Maps
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. One of: tournament league (for League Arenas) arena (for all other Arenas) challenge custom (for all other games sources) The values for this field may change in the near future.

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, wrapped. 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
  }
}

{% hint style="info" %} 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. {% endhint %}

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

{% code title="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",
  "customizations":{
    "color":"#26CF04",
    "head":"smile",
    "tail":"bolt"
  }
}

{% endcode %}

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. If the Battlesnake timed out and failed to respond, the game timeout will be returned (game.timeout) Example: "500"
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"
customizations	object	The collection of customizations applied to this Battlesnake that represent how it is viewed. Follows the same rules as in the GET request. Example: {"color":"#888888", "head":"default", "tail":"default" }

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

{% code title="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", ... }
  ]
}

{% endcode %}

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

Game Maps

Game maps are defined in the BattlesnakeOfficial/rules repo, inside the maps package. Known maps currently include:

Map ID	Description
standard	Standard snake placement and food spawns
empty	Standard snake placement with no food spawns
arcade_maze	Arcade Maze
royale	Royale
solo_maze	Solo Maze where you need to find the food
hz_inner_wall	Inner Border
hz_rings	Concentric Rings
hz_columns	Columns
hz_rivers_bridges	Rivers and Bridges
hz_spiral	Spiral
hz_scatter	Scatter
hz_grow_box	Directional Expanding Box
hz_expand_box	Expanding Box
hz_expand_scatter	Expanding Scatter