::|CONTENTS
- Basic Syntax
- Commands
- Pagination
- Object Types
- Examples
- POST Examples
- Response Formats
- See Also
Battle of the Bits offers a fully public API. Please do not abuse; request throttling and/or api access tokens might be implemented in the future. Make sure to use
https:// for all requests or they will fail. Please enjoy.
Basic Syntax
battleofthebits.com/api/v1/{object_type}/{command}(/{param0}(/{param1}(/{param2(..))))
A dynamically generated list of object_types with their allotted commands and properties is available here:
https://battleofthebits.com/api/v1/documentation/index
Commands
load
battleofthebits.com/api/v1/{object_type}/load/{object_id}
list
battleofthebits.com/api/v1/{object_type}/list(/{page_number=0}(/{page_length=25}))
Lists can be sorted by property values by using the GET method
?sort={object_property}&desc=true
The
desc variable is optional; defaults to ascending.
Filters can be applied using the GET method.
?filters={defined_filters}
Filters are defined by pairing a key and value with
~. Multiple filters can be defined by using
^ for separation.
(example:
/api/v1/botbr/list/?filters=level~17^class~chipist)
*this may be deprecated in future versions
list via POST
Conditionals can be applied using the POST method. These are much more versatile than the Filters using GET. The best way to understand how it works is to open your web browser's developer tools and observe the network tab while interacting with BotB's
browser. The API expects a JSON-style string array of filter objects using the
application/x-www-form-urlencoded or
multipart/form-data methods.
"conditions": [
{ "property": "title", "operator": "LIKE", "operand": "%ass%" },
{ "property": "score_favs", "operator": ">", "operand": "40" },
{ "property": "format_token", "operator": "like", "operand": "%mod%" },
{ "property": "yt", "operator": "is", "operand": "NULL" }
]
List of Operator Symbols: < > = >= <= !=
SQL style Operator Words:
-
"IN" (operand must be an array)
-
"IS" or "IS NOT" (operand must be "NULL")
-
"LIKE" (operand is text with % prefix/suffix for wildcards)
POST requests are only accepted in the form data format. Make sure a Content-Type request header is set to either
application/x-www-form-urlencoded or
multipart/form-data .
search
battleofthebits.com/api/v1/{object_type}/search/{substring}(/{page_number=0}(/{page_length=25}))
Each object type that supports the search command has a single searchable property such as 'name' or 'title'. This property is chosen within the system and is not modifiable by the end user.
random
battleofthebits.com/api/v1/{object_type}/random
I'm feeling lucky!
Pagination is optional and only available for commands that support it. The
page_number is zero based and the default
page_length is 25 objects. The maximum number of objects that can be pulled in a single call is 500.
Object Types
Available object types are:
battle - a battle, either a major battle or an X Hour Battle (XHB).
botbr - a BotBr, user of the site.
botbr_points - the points for a BotBr for a specific class.
entry - an entry, a single submission to a battle.
favorite - a single favorite on an entry.
format - a battle format.
group_thread - a thread of messages; forum threads and comments on entries/battles/BotBr profiles are group threads.
lyceum_article - an article on the Lyceum.
palette - an on-site color palette.
playlist - a single playlist containing entries.
playlist_to_entry - join table joining playlist and entry.
tag - a single tag given to an entry.
botbr_stats - a single statistic for a BotBr.
daily_stats - the site-wide statistic for a specific day.
botbr_points, favorite, format, palette, botbr_stats, and daily_stats are not searchable.
Examples
Here are some example-requests to make it more clear:
Getting all currently ongoing battles:
https://battleofthebits.com/api/v1/battle/current
Search for a battle by name:
https://battleofthebits.com/api/v1/battle/search/Winter+Chip+II
Search for a lyceum article by name:
https://battleofthebits.com/api/v1/lyceum_article/search/API
Get a BotBr by name:
https://battleofthebits.com/api/v1/botbr/list?filters=name~puke7
https://battleofthebits.com/api/v1/botbr/search/puke7
Get a random entry:
https://battleofthebits.com/api/v1/entry/random
Get an entry by id:
https://battleofthebits.com/api/v1/entry/load/12345
Get the top 5 BotBr:
https://battleofthebits.com/api/v1/botbr/list/0/5?sort=points&desc=true
Get the top 5 BotBr filtered by class Chipist:
https://battleofthebits.com/api/v1/botbr/list/0/5?filters=class~Chipist&sort=points&desc=true
Get all (or the first 250) entries of a battle:
https://battleofthebits.com/api/v1/entry/list/0/250?filters=battle_id~1234
POST Examples
Firki doesn't have proper code blocks, so hang in there for a bit, ok?
XHBs on June 1st '26 with XMLHttpRequest
xhr = new XMLHttpRequest();
xhr.open("POST", "https://battleofthebits.com/api/v1/battle/list");
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.send( encodeURI('conditions[0][property]=end&conditions[0][operator]=LIKE&conditions[0][operand]=2026-06-01%&conditions[1][property]=type&conditions[1][operator]=LIKE&conditions[1][operand]=3') );
with fetch
fetch("https://battleofthebits.com/api/v1/battle/list", {
. . . . method:"POST",
. . . . . . . . headers: {
. . . . . . . . . . . . "Content-Type": "application/x-www-form-urlencoded"
. . . . . . . . },
. . . . body: encodeURI(
. . . . . . . . 'conditions[0][property]=end&conditions[0][operator]=LIKE&conditions[0][operand]=2026-06-01%&conditions[1][property]=type&conditions[1][operator]=LIKE&conditions[1][operand]=3'
. . . . )
}).then(result => {
. . . . . . . . console.log(result.body);
});
with jQuery
$.ajax({
type: "POST",
. . . . url: "https://battleofthebits.com/api/v1/battle/list",
. . . . data: {
. . . . . . . . conditions: [
. . . . . . . . . . . . {property: "start", operand: "LIKE", operator: "2026-06-01%"},
. . . . . . . . . . . . {property: "type", operand: "LIKE", operator: "3"},
. . . . . . . . ],
. . . . . . . . sort: "start",
. . . . . . . . desc: true
. . . . }
});
Response Formats
The BotB API v1 default response format is a JSON object. XML is also available by either setting the format via GET
?format=xml or adding the
.xml extension to the URI.
See Also
pyBotB Battle of the Bits API Overview
