API docs by Redocly

Unofficial V1 API Docs for Speedrun.com (1.0)

Download OpenAPI specification:

License: MIT

About

Unofficial Speedrun.com API docs Built by Flammableassassin

If you wish to contribute feel free to here https://github.com/flamableassassin/openapi-docs/

The official docs are here: https://github.com/speedruncomorg/api


This spec is based on my interpretation of the official docs

In reality this spec is more than likely missing parameters, properties on schemas and endpoints. If you find one of these please open an issue or contribute via a pull request

Categories

Categories are the different rulesets for speedruns. Categories are either per-game or per-level (if the game uses individual levels), both can be accessed via this resource.

This resource is meant to perform ID-based lookups. That's why there is no GET /categories to get a flat list of all categories across all games. If you want to get the categories for a game, use GET /v1/games/{gameid}/categories.

https://github.com/speedruncomorg/api/blob/master/version1/categories.md

Category

id
required
string

Values can vary in length

name
required
string
weblink
required
string <uri>

The URL to the category leaderboard on the website

type
required
string
Enum: "per-game" "per-level"

Categories are either per-game or per-level (if the game uses individual levels)

rules
required
string

Freeform text with some basic, undocumented speedrun.com markup

required
object

Players is the number of participants per run in this category.

miscellaneous
required
boolean

Miscellaneous categories are usually not shown directly on the leaderboards, but are otherwise nothing special

required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Retrieve a single category, identified by its ID

https://github.com/speedruncomorg/api/blob/master/version1/categories.md#get-categoriesid
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
embed
Array of strings
Items Enum: "game" "variables"

Embed additional resources into the response. See embedding for more info.

Responses

Response samples

Content type
application/json
{}

Retrieve all variables that are applicable to the given category

This will retrieve all variables that are applicable to the given category.

  • per-level categories will not show the variables for runs completing the entire game.
  • per-game categories will not show the variables for individual level runs.
https://github.com/speedruncomorg/api/blob/master/version1/categories.md#get-categoriesidvariables
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
orderby
string
Default: "pos"
Enum: "name" "mandatory" "user-defined" "pos"
Order by Description
name sorts alphanumerically by the variable name
mandatory sorts by mandatory flag
user-defined sorts by user-defined flag
pos (default) uses the order as defined by the game moderator
direction
string
Enum: "asc" "desc"

The direction to sort the results

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve the records of the given category.

This will retrieve the records (first three places) of the given category. If it's a full-game category, the result will be a list containing one leaderboard, otherwise the result will contain one leaderboard for each level of the game the category belongs to.

https://github.com/speedruncomorg/api/blob/master/version1/categories.md#get-categoriesidrecords
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
top
number

Only return the top N places

skip-empty
boolean

Skips empty values

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
embed
Array of strings
Items Enum: "game" "category" "level" "players" "regions" "platforms" "variables"

Embed additional resources into the response. See embedding for more info.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {}
}

Developers

Developers are the persons and/of studios responsible for developing games, for example Acclaim Entertainment, Bethesda Softworks, Edmund McMillen etc.

https://github.com/speedruncomorg/api/blob/master/version1/developers.md

Developer

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all developers

https://github.com/speedruncomorg/api/blob/master/version1/developers.md#get-developers
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the developer name

Responses

Response samples

Content type
application/json
{}

Retrieve a single developer by its id

https://github.com/speedruncomorg/api/blob/master/version1/developers.md#get-developersid
Authorizations:
None
path Parameters
id
required
string

The id of a developer

Responses

Response samples

Content type
application/json
{}

Engines

Engines are software frameworks used in the creation of games, for example the DOOM engine, Unreal Engine, Geo-Mod etc.

https://github.com/speedruncomorg/api/blob/master/version1/engines.md

Engine

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all engines

https://github.com/speedruncomorg/api/blob/master/version1/engines.md#get-engines
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the name

Responses

Response samples

Content type
application/json
{}

Retrieve a single engine by its id

https://github.com/speedruncomorg/api/blob/master/version1/engines.md#get-enginesid
Authorizations:
None
path Parameters
id
required
string

The id of a engine

Responses

Response samples

Content type
application/json
{}

Games

Games are the things users do speedruns in. Games are associated with regions (US, Europe, ...), platforms (consoles, handhelds, ...), genres, engines, developers, game types, publishers, categories, levels and custom variables (like speed=50/100/150cc in Mario Kart games).

Games that are not part of a series are categorized in the "N/A" series for backwards compatibility.

https://github.com/speedruncomorg/api/blob/master/version1/games.md

Game

id
required
string

Values can vary in length

required
object (GameNames)
abbreviation
required
string

** Do not ** use the abbreviation to manually construct a game's full web URL, instead always use the provided weblink. We might change the URL scheme on the frontend at any time without prior notice!

weblink
required
string <uri>

Link to get to this game's page intended for humans, links are meant for the API client.

released
required
integer
Deprecated

Legacy value that has been superseded by release-date.

release-date
required
string <date>
required
object (Ruleset)
romhack
required
boolean
Deprecated

Legacy value that has been superceded by gametypes.

required
Array of strings or object

List of game types IDs set for the game. This list can be empty.

required
Array of strings or object

List of platform IDs the game can be played on. This list can be empty.

required
Array of strings or object

List of region IDs the game is available in. This list can be empty.

required
Array of strings or object

List of genre IDs set for the game. This list can be empty.

required
Array of strings or object

List of engine IDs set for the game. This list can be empty.

required
Array of strings or object

List of developer IDs set for the game. This list can be empty.

required
Array of strings or object

List of publisher IDs set for the game. This list can be empty.

required
Moderators (object) or object

Mapping of user IDs to their roles within the game. Possible roles are moderator and super-moderator (super moderators can appoint other users as moderators).

required
string or null

Can be null for games that have been added in the early days of speedrun.com.

required
object

Links to images that are used for that game on speedrun.com

required
Array of objects (Links)

links.romhacks is a legacy value. New code should use derived-games instead. links.series can appear multiple times, as games can be in multiple series.

{}

Get all games

Note that giving invalid values for platform, region or moderator will result in an HTTP 404 error instead of an empty list. This is on purpose, because asking to filter by non-existing elements should be something an API client should notice.

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-games
Authorizations:
None
query Parameters
embed
Array of strings
Items Enum: "levels" "categories" "moderators" "gametypes" "platforms" "regions" "genres" "engines" "developers" "publishers" "variables"

Embed additional resources into the response. See embedding for more info.

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

orderby
string
Default: "name.int"
Enum: "name.int" "name.jap" "abbreviation" "released" "created" "similarity"
order by Description
name.int (default) sorts alphanumerically by the international name
name.jap sorts alphanumerically by the japanese name
abbreviation sorts alphanumerically by the abbreviation
released sorts by the release date
created sorts by the date when the game was added on speedrun.com
similarity sorts by string similarity; only available when searching games by name; default when searching by name
name
string

When given, performs a fuzzy search across game names and abbreviations

abbreviation
string

When given, performs an exact-match search for this abbreviation

released
number

When given, restricts to games released in that year

gametype
string

Game type ID; when given, restricts to that game type

genre
string

Genre ID; when given, restricts to that genre

engine
string

Engine ID; when given, restricts to that engine

developer
string

Developer ID; when given, restricts to that developer

publisher
string

Publisher ID; when given, restricts to that publisher

moderator
string

Moderator ID; when given, only games moderated by that user will be returned

romhack
boolean
Deprecated

Legacy parameter, do not use this in new code; whether or not to include games with game types (if this parameter is not set, game types are included; if it is set to a true value, only games with game types will be returned, otherwise only games without game types are returned)

_bulk
boolean

Enable bulk access

Responses

Response samples

Content type
application/json
{}

Retrieve a single game by its id

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesid
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

Responses

Response samples

Content type
application/json
{}

Retrieve all categories of a given game

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesidcategories
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

query Parameters
direction
string
Enum: "asc" "desc"

The direction to sort the results

miscellaneous
boolean
Query Parameter Type Description
miscellaneous bool when given, filters (out) misc categories
orderby
string
Default: "pos"
Enum: "name" "pos" "miscellaneous"
Order by Description
name sorts alphanumerically by the category name
miscellaneous sorts by miscellaneous flag
pos (default) uses the order as defined by the game moderator

Responses

Response samples

Content type
application/json
{}

Retrieve all levels of a given game

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesidvariables
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

query Parameters
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "pos"
Enum: "name" "pos"
Order by Description
name sorts alphanumerically by the level name
pos (default) uses the order as defined by the game moderator

Responses

Response samples

Content type
application/json
{}

Retrieve all variables of a given game

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesidvariables
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

query Parameters
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "pos"
Enum: "name" "mandatory" "user-defined" "pos"
order by Description
name sorts alphanumerically by the variable name
mandatory sorts by mandatory flag
user-defined sorts by user-defined flag
pos (default) uses the order as defined by the game moderator

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve all games that have the given game

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesidderived-games
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

query Parameters
embed
Array of strings
Items Enum: "levels" "categories" "moderators" "gametypes" "platforms" "regions" "genres" "engines" "developers" "publishers" "variables"

Embed additional resources into the response. See embedding for more info.

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name.int"
Enum: "name.int" "name.jap" "abbreviation" "released" "created" "similarity"
order by Description
name.int (default) sorts alphanumerically by the international name
name.jap sorts alphanumerically by the japanese name
abbreviation sorts alphanumerically by the abbreviation
released sorts by the release date
created sorts by the date when the game was added on speedrun.com
similarity sorts by string similarity; only available when searching games by name; default when searching by name
name
string

When given, performs a fuzzy search across game names and abbreviations

abbreviation
string

When given, performs an exact-match search for this abbreviation

released
number

When given, restricts to games released in that year

gametype
string

Game type ID; when given, restricts to that game type

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

genre
string

Genre ID; when given, restricts to that genre

engine
string

Engine ID; when given, restricts to that engine

developer
string

Developer ID; when given, restricts to that developer

publisher
string

Publisher ID; when given, restricts to that publisher

moderator
string

Moderator ID; when given, only games moderated by that user will be returned

_bulk
boolean

Enable bulk access

Responses

Response samples

Content type
application/json
{}

Retrieve the records for every (category,level) combination of the given game.

https://github.com/speedruncomorg/api/blob/master/version1/games.md#get-gamesidrecords
Authorizations:
None
path Parameters
id
required
string

The id of a game or its abbreviation

query Parameters
embed
Array of strings
Items Enum: "game" "category" "level" "players" "regions" "platforms" "variables"

Embed additional resources into the response. See embedding for more info.

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
miscellaneous
boolean
Query Parameter Type Description
miscellaneous bool when given, filters (out) misc categories
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
top
number

Only return the top N places

skip-empty
boolean

Skips empty values

scope
string
Default: "all"
Enum: "full-game" "levels" "all"

when set to full-game, only full-game categories will be included; when set to levels, only individual levels are returned; default is all

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {}
}

Game Types

Game types are classifications for unofficial games, for example ROM Hack, Fangame, Modification etc.

https://github.com/speedruncomorg/api/blob/master/version1/gametypes.md

GameType

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all game types

https://github.com/speedruncomorg/api/blob/master/version1/gametypes.md#get-gametypes
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the name

Responses

Response samples

Content type
application/json
{}

Retrieve a single game type by its id

https://github.com/speedruncomorg/api/blob/master/version1/gametypes.md#get-gametypesid
Authorizations:
None
path Parameters
id
required
string

The id of a game type

Responses

Response samples

Content type
application/json
{}

Genres

Genres are classifications for games, for example Action, JRPG, Rogue-like etc.

https://github.com/speedruncomorg/api/blob/master/version1/genres.md

Genre

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all genres

https://github.com/speedruncomorg/api/blob/master/version1/genres.md#get-genres
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the name

Responses

Response samples

Content type
application/json
{}

Retrieve a single genre by its id

https://github.com/speedruncomorg/api/blob/master/version1/genres.md#get-genresid
Authorizations:
None
path Parameters
id
required
string

The id of a genre

Responses

Response samples

Content type
application/json
{}

Guests

Sometimes, speedrun.com has runs done by players that have no account on the site yet. These runners are called "guests" in the API. Except for a name, there is nothing we know about them.

https://github.com/speedruncomorg/api/blob/master/version1/guests.md

Guest

name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Retrieve a guest, identified by their name.

https://github.com/speedruncomorg/api/blob/master/version1/genres.md#get-genresid
Authorizations:
None
path Parameters
name
required
string

The name of a guest, case-insensitive.

Responses

Response samples

Content type
application/json
{}

Leaderboards

Leaderboards contain non-obsolete runs, sorted by time descending. In contrast to raw runs, leaderboards are automatically grouped according to the game/category/level rules that the moderators have defined.

https://github.com/speedruncomorg/api/blob/master/version1/leaderboards.md

Leaderboard

weblink
required
string <uri>
required
string or object
required
string or object
required
null or string or object
required
null or string or object
required
null or string or object
emulators
required
null
video-only
required
boolean
timing
required
string
required
object (VariableMapping)
required
Array of objects
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{
  • "data": {
    }
}

Get a full-game leaderboard

https://github.com/speedruncomorg/api/blob/master/version1/leaderboards.md#get-leaderboardsgamecategorycategory
Authorizations:
None
path Parameters
game
required
string

Game ID or abbreviation.

category
required
string

Category ID or abbreviation.

query Parameters
embed
Array of strings
Items Enum: "game" "category" "level" "players" "regions" "platforms" "variables"

Embed additional resources into the response. See embedding for more info.

top
number

Only return the top N places

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

emulators
boolean

When not given, real devices and emulators are shown. When set to a true value, only emulators are shown, else only real devices are shown

video-only
boolean
Default: false

When set to a true value, only runs with a video will be returned

timing
string
Enum: "realtime" "realtime_noloads" "ingame"

Controls the sorting

date
string <date>

ISO 8601 date string; when given, only returns runs done before or on this date

object

To filter by custom variables, name the query string parameter var-{variable ID here} and use the value ID as the value (for example, ?var-m5ly6jn4=p12z471x). Please refer to the official docs for more information

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an individual-level leaderboard

https://github.com/speedruncomorg/api/blob/master/version1/leaderboards.md#get-leaderboardsgamelevellevelcategory
Authorizations:
None
path Parameters
game
required
string

Game ID or abbreviation.

level
required
string

Level ID or abbreviation.

category
required
string

Category ID or abbreviation.

query Parameters
embed
Array of strings
Items Enum: "game" "category" "level" "players" "regions" "platforms" "variables"

Embed additional resources into the response. See embedding for more info.

top
number

Only return the top N places

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

emulators
boolean

When not given, real devices and emulators are shown. When set to a true value, only emulators are shown, else only real devices are shown

video-only
boolean
Default: false

When set to a true value, only runs with a video will be returned

timing
string
Enum: "realtime" "realtime_noloads" "ingame"

Controls the sorting

date
string <date>

ISO 8601 date string; when given, only returns runs done before or on this date

object

To filter by custom variables, name the query string parameter var-{variable ID here} and use the value ID as the value (for example, ?var-m5ly6jn4=p12z471x). Please refer to the official docs for more information

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Levels

Levels are the stages/worlds/maps within a game. Not all games have levels.

This resource is meant to perform ID-based lookups. That's why there is no GET /levels to get a flat list of all levels across all games. To only get the levels for one game, use the /levels collection on the game itself.

https://github.com/speedruncomorg/api/blob/master/version1/levels.md

Level

id
required
string
name
required
string
weblink
required
string <uri>
rules
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Retrieve a single level, identified by its ID

https://github.com/speedruncomorg/api/blob/master/version1/levels.md#get-levelsid
Authorizations:
None
path Parameters
id
required
string

The id of a level

query Parameters
embed
Array of strings
Items Enum: "categories" "variables"

Embed additional resources into the response. See embedding for more info.

Responses

Response samples

Content type
application/json
{}

Retrieve all categories that are applicable to the given level

https://github.com/speedruncomorg/api/blob/master/version1/levels.md#get-levelsidcategories
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
orderby
string
Default: "pos"
Enum: "name" "miscellaneous" "pos"
Order by Description
name sorts alphanumerically by the level name
miscellaneous sorts by miscellaneous flag
pos (default) uses the order as defined by the game moderator
direction
string
Enum: "asc" "desc"

The direction to sort the results

miscellaneous
boolean
Query Parameter Type Description
miscellaneous bool when given, filters (out) misc categories

Responses

Response samples

Content type
application/json
{}

Retrieve all variables that are applicable to the given level

https://github.com/speedruncomorg/api/blob/master/version1/levels.md#get-levelsidvariables
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
orderby
string
Default: "pos"
Enum: "name" "mandatory" "user-defined" "pos"
Order by Description
name sorts alphanumerically by the variable name
mandatory sorts by mandatory flag
user-defined sorts by user-defined flag
pos (default) uses the order as defined by the game moderator
direction
string
Enum: "asc" "desc"

The direction to sort the results

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve the records of the given level

Retrieve the records (first three places) of the given level.

https://github.com/speedruncomorg/api/blob/master/version1/levels.md#get-levelsidrecords
Authorizations:
None
path Parameters
id
required
string

The id of a category

query Parameters
top
number

Only return the top N places

skip-empty
boolean

Skips empty values

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
embed
Array of strings
Items Enum: "game" "category" "level" "players" "regions" "platforms" "variables"

Embed additional resources into the response. See embedding for more info.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {}
}

Notifications

Notifications are system-generated messages sent to users when certain events concerning them happen on the site, like somebody liking a post or a run being verified.

https://github.com/speedruncomorg/api/blob/master/version1/notifications.md

Notification

id
required
string
created
required
string <date-time>
status
required
string
Enum: "read" "unread"
text
required
string
required
object
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Retrieve the notifications for the currently authenticated user

https://github.com/speedruncomorg/api/blob/master/version1/notifications.md#get-notifications
Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{}

Platforms

Platforms are hardware devices that run games, for example PC, NES, PS2 etc.

https://github.com/speedruncomorg/api/blob/master/version1/platforms.md

Platform

id
required
string
name
required
string
released
required
integer
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all platforms

https://github.com/speedruncomorg/api/blob/master/version1/platforms.md#get-platforms
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Enum: "name" "released"
order by Description
name (default) sorts alphanumerically by the platform name
released sorts by the year the platform was released

Responses

Response samples

Content type
application/json
{}

Retrieve a single platform by its id

https://github.com/speedruncomorg/api/blob/master/version1/platforms.md#get-platformsid
Authorizations:
None
path Parameters
id
required
string

The id of a platform

Responses

Response samples

Content type
application/json
{}

Profile

The profile is the user resource of the currently authenticated user. This is useful to see what user a given API key belongs to.

apiKey

See the official authentication docs for more info

Security Scheme Type: API Key
Header parameter name: X-API-Key
https://github.com/speedruncomorg/api/blob/master/version1/profile.md

User

id
required
string
required
object (BaseName)
weblink
required
string <uri>
required
object
role
required
string
Enum: "banned" "user" "trusted" "moderator" "admin" "programmer"
required
null or string
required
null or object
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
Array of objects (Links) [ items ]
{}

Retrieve the profile for the currently authenticated user

https://github.com/speedruncomorg/api/blob/master/version1/profile.md#get-profile
Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{}

Publishers

Publishers are companies that publish (games)(#tag/games), for example Capcom, SEGA, Midway Games etc.

https://github.com/speedruncomorg/api/blob/master/version1/publisher.md

Publisher

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all Publishers

https://github.com/speedruncomorg/api/blob/master/version1/publishers.md#get-publishers
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the name

Responses

Response samples

Content type
application/json
{}

Retrieve a single publisher by its id

https://github.com/speedruncomorg/api/blob/master/version1/publishers.md#get-publishersid
Authorizations:
None
path Parameters
id
required
string

The id of a publisher

Responses

Response samples

Content type
application/json
{}

Region

Regions represent the different distribution zones in which (games)(#tag/games) are published, for example the US, Europe or Japan.

https://github.com/speedruncomorg/api/blob/master/version1/region.md

Region

id
required
string
name
required
string
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all regions

https://github.com/speedruncomorg/api/blob/master/version1/regions.md#get-regions
Authorizations:
None
query Parameters
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "name"
Value: "name"
order by Description
name (default) sorts alphanumerically by the name

Responses

Response samples

Content type
application/json
{}

Retrieve a single region by its id

https://github.com/speedruncomorg/api/blob/master/version1/regions.md#get-regionsid
Authorizations:
None
path Parameters
id
required
string

The id of a region

Responses

Response samples

Content type
application/json
{}

Retrieve a single region by its id

https://github.com/speedruncomorg/api/blob/master/version1/users.md#get-usersid
Authorizations:
None
path Parameters
id
required
string

The id or username of a user

Responses

Response samples

Content type
application/json
{}

Runs

Runs are the meat of our business at speedrun.com. A run is a finished attempt to play a game, adhering to that game's ruleset. Invalid attempts (use of cheats etc) or obsolete runs (the ones superseded by a better time by the same player(s) in the same ruleset) still count as runs and are available via API.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md

Run

id
required
string
weblink
required
string <uri>
required
string or object
required
null or string or object
required
string or object
required
null or object
comment
required
string
required
object (RunStatus)
required
Array of objects or object
required
string or null
required
string or null
required
object (Time)
required
object
required
null or object
required
object (VariableMapping)

Values is a mapping from variables to values

required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all runs

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#get-runs
Authorizations:
None
query Parameters
embed
string
Enum: "game" "category" "level" "players" "region" "platform"

Embed additional resources into the response. See embedding for more info.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#embeds
offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

orderby
string
Default: "game"
Enum: "game" "category" "level" "platform" "region" "emulated" "date" "submitted" "status" "verify-date"
Order by Description
game (default) Sorts by the game the run was done in
category Sorts by the category the run was done in
level Sorts by the level the run was done in
platform Sorts by the console used for the run
region Sorts by the console region the run was done in
emulated Sorts by whether or not a run is done via emulator
date Sorts by the date the run happened on
submitted Sorts by the date when the run was submitted to speedrun.com
status Sorts by verification status
verify-date Sorts by the date the run was verified on
user
string

User ID; when given, only returns runs played by that user

guest
string

When given, only returns runs done by that guest

examiner
string

User ID; when given, only returns runs examined by that user

game
string

Game ID; when given, restricts to that game

level
string

Level ID; when given, restricts to that level

category
string

Category ID; when given, restricts to that category

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

emulated
boolean

When 1, yes or true, only games run on emulator will be returned

status
string

Filters by run status; new, verified and rejected are possible values for this parameter

Responses

Response samples

Content type
application/json
{}

Submit a new run.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#post-runs
Authorizations:
apiKey
Request Body schema: application/json
category
required
string (Encoded-id) <= 50 characters ^[a-z0-9]+$
level
string (Encoded-id) <= 50 characters ^[a-z0-9]+$
date
string <date>
region
string (Encoded-id) <= 50 characters ^[a-z0-9]+$
platform
required
string (Encoded-id) <= 50 characters ^[a-z0-9]+$
verified
boolean
Default: false
required
object non-empty
Array of objects or objects (Run-Submit-Player-List) non-empty
emulated
boolean
Default: false
video
string <= 255 characters
comment
string <= 2000 characters
splitsio
string <= 50 characters
object

Responses

Request samples

Content type
application/json
{
  • "run": {
    }
}

Response samples

Content type
application/json
{}

Get a run

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#get-runsid
Authorizations:
None
path Parameters
id
required
string

The id of a run

query Parameters
embed
string
Enum: "game" "category" "level" "players" "region" "platform"

Embed additional resources into the response. See embedding for more info.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#embeds

Responses

Response samples

Content type
application/json
{}

Delete a run

This method allows an authenticated user to delete a run. Regular users can only delete their own runs, whereas [global] mods can delete runs by other users as well.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#delete-runsid
Authorizations:
apiKey
path Parameters
id
required
string

The id of a run

Responses

Response samples

Content type
application/json
{}

Modify a runs status

By PUTing to this endpoint, a user with sufficient permissions (i.e. a global moderator or a game moderator) can change the verification status of the run identified by its id.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#put-runsidstatus
Authorizations:
apiKey
path Parameters
id
required
string

The id of a run

Request Body schema: application/json
required
object or object

Responses

Request samples

Content type
application/json
Example
{
  • "status": {
    }
}

Response samples

Content type
application/json
{ }

Modify a runs players

By PUTing to this endpoint, a user with sufficient permissions (i.e. a global moderator or a game moderator) can change list of players that participated in a run.

https://github.com/speedruncomorg/api/blob/master/version1/runs.md#put-runsidplayers
Authorizations:
apiKey
path Parameters
id
required
string

The id of a run

Request Body schema: application/json
required
Array (non-empty)
One of
rel
required
string
Value: "user"
id
required
string (Encoded-id) <= 50 characters ^[a-z0-9]+$

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{}

Series

Series are collections of games that have been released in context to each other, for example the "GTA" series contains all the games of this franchise. As a series is most often formed after a number of games have been published, many games do not belong to a specific series and are therefore categorized in the "Other" series. As time progresses, games can be moved in their own series, so be prepared for the series-game relationship to change.

https://github.com/speedruncomorg/api/blob/master/version1/series.md

Series

id
required
string
required
object (GameNames)
abbreviation
required
string
weblink
required
string <uri>
required
Moderators (object) or object
required
string or null
required
object (Asset)
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{}

Get all series

https://github.com/speedruncomorg/api/blob/master/version1/series.md#get-series
Authorizations:
None
query Parameters
embed
Array of strings
Items Value: "moderators"

Embed additional resources into the response. See embedding for more info.

name
string

when given, performs a fuzzy search across series names and abbreviations

abbreviation
string

When given, performs an exact-match search for this abbreviation

moderator
string

Moderator ID; when given, only series moderated by that user will be returned

orderby
string
Default: "name.int"
Enum: "name.int" "name.jap" "abbreviation" "created"
Order by Description
name.int (default) Sorts alphanumerically by the international name
name.jap Sorts alphanumerically by the japanese name
abbreviation Sorts alphanumerically by the abbreviation
created Sorts by the date when the series was added on speedrun.com
direction
string
Enum: "asc" "desc"

The direction to sort the results

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md

Responses

Response samples

Content type
application/json
{}

Retrieve a single series by its id or abbreviation

https://github.com/speedruncomorg/api/blob/master/version1/users.md#get-seriesid
Authorizations:
None
path Parameters
id
required
string

The id or abbreviation of a series

Responses

Response samples

Content type
application/json
{}

Retrieve all games of a given series

https://github.com/speedruncomorg/api/blob/master/version1/series.md#get-seriesidgames
Authorizations:
None
path Parameters
id
required
string

The id or abbreviation of a series

query Parameters
embed
Array of strings
Items Enum: "levels" "categories" "moderators" "gametypes" "platforms" "regions" "genres" "engines" "developers" "publishers" "variables"

Embed additional resources into the response. See embedding for more info.

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
direction
string
Enum: "asc" "desc"

The direction to sort the results

platform
string

Platform ID; when given, restricts to that platform

region
string

Region ID; when given, restricts to that region

name
string

When given, performs a fuzzy search across game names and abbreviations

abbreviation
string

When given, performs an exact-match search for this abbreviation

released
number

When given, restricts to games released in that year

gametype
string

Game type ID; when given, restricts to that game type

genre
string

Genre ID; when given, restricts to that genre

engine
string

Engine ID; when given, restricts to that engine

developer
string

Developer ID; when given, restricts to that developer

publisher
string

Publisher ID; when given, restricts to that publisher

moderator
string

Moderator ID; when given, only games moderated by that user will be returned

romhack
boolean
Deprecated

Legacy parameter, do not use this in new code; whether or not to include games with game types (if this parameter is not set, game types are included; if it is set to a true value, only games with game types will be returned, otherwise only games without game types are returned)

_bulk
boolean

Enable bulk access

Responses

Response samples

Content type
application/json
{}

Users

Users are the individuals who have registered an account on speedrun.com. Users submit (their) runs and moderate games, besides other things that are not covered by this API (like writing posts in the forums).

The API only returns public user information, so things like the e-mail address, site settings etc. are not accessible.

https://github.com/speedruncomorg/api/blob/master/version1/users.md

User

id
required
string
required
object (BaseName)
weblink
required
string <uri>
required
object
role
required
string
Enum: "banned" "user" "trusted" "moderator" "admin" "programmer"
required
null or string
required
null or object
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
null or object (UserSocial)
required
Array of objects (Links) [ items ]
{}

Get all users

https://github.com/speedruncomorg/api/blob/master/version1/users.md#get-users
Authorizations:
None
query Parameters
lookup
string

when given, searches the value (case-insensitive exact-string match) across user names, URLs and social profiles; all other query string filters are disabled when this is given

name
string

only returns users whose name/URL contains the given value; the comparision is case-insensitive

twitch
string

searches for Twitch usernames

hitbox
string

searches for Hitbox usernames

twitter
string

searches for Twitter usernames

speedrunslive
string

searches for SpeedRunsLive usernames

orderby
string
Default: "name.int"
Enum: "name.int" "name.jap" "signup" "role"
Order by Description
name.int (default) Sorts alphanumerically by the international name
name.jap Sorts alphanumerically by the japanese name
signup Sorts by the signup date
role Sorts by the user role
direction
string
Enum: "asc" "desc"

The direction to sort the results

offset
number >= 0

Advance to the next set of elements

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md
max
number [ 1 .. 200 ]

The maximum number of elements to return

https://github.com/speedruncomorg/api/blob/master/version1/pagination.md

Responses

Response samples

Content type
application/json
{}

Retrieve Personal Bests of the given user

https://github.com/speedruncomorg/api/blob/master/version1/users.md#get-usersidpersonal-bests
Authorizations:
None
path Parameters
id
required
string

The id or username of a user

query Parameters
top
number >= 1

When given, only PBs with a place equal or better than this value (e.g. top=1 returns all World Records of the given user)

series
string

When given, restricts the result to games and romhacks in that series; can be either a series ID or abbreviation

game
string

When given, restricts the result to that game; can be either a game ID or abbreviation

Responses

Response samples

Content type
application/json
{}

Variables

Variables are custom criteria to distinguish between runs done in the same category or level. The speed in Mario Kart games (which can be 50cc, 100cc or 150cc) is an example for a variable that has 3 possible values.

Variables are defined per-game and can be applicable to either all runs for this game or just full-game or individual-level (IL) runs. Variables can also be restricted to a category. It is therefore important to understand how to get the correct set of variables:

https://github.com/speedruncomorg/api/blob/master/version1/variables.md

Variable

id
required
string
name
required
string
required
null or string
required
object
mandatory
required
boolean
user-defined
required
boolean
obsoletes
required
boolean
required
object
is-subcategory
required
boolean
required
Array of objects (Links)

Links for traversing the API or links to external sites (e.g for help in 404 response)

{
  • "id": "wzx7q875",
  • "name": "cc",
  • "category": null,
  • "scope": {
    },
  • "mandatory": true,
  • "user-defined": false,
  • "obsoletes": false,
  • "values": {
    },
  • "is-subcategory": true,
  • "links": []
}

Retrieve a single variable by its id

https://github.com/speedruncomorg/api/blob/master/version1/variables.md#get-variablesid
Authorizations:
None
path Parameters
id
required
string

The id of a variable

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}