S&box Wiki

Backend API

Backend API

This API is prone to changes at any time - and therefore this guide might go out of date. If something doesn't line up, it probably means the API was changed and that this page needs updating.

This page is an analysis of the API used for the dev site and the in-game menus; please be aware that this may change at any time and that none of this information is official. All endpoints are on the https://apix.facepunch.com/api/ domain.

To access the API, your requests require a header of X-Api-Version followed by the current version of the game

(e.g. 'X-Api-Version':'25').

Types

NOTE: Nullable types are suffixed with ?. This API is subject to change and probably will do so before release.

PackageType

An enum specifying the different package types.

Starting at 1:

Index Name
1 Map
2 Gamemode

DownloadInfo

An object containing a package's download type (where it's hosted, i.e. github), and the URL to access it. The crc and size properties are only available for upload types.

Name Type Description
type string The download type of the package
url string Download URL of the package
crc uint? Cyclic redundancy check code
size int? Size of the download in bytes

Asset

This is returned by /sbox/asset/get.

Name Type Description
asset Package This asset's package info

Package

These are used in various places and are used to describe assets like gamemodes and maps.

Name Type Description
org Org The organisation owning this package
ident string This package's identifier
title string This package's human-friendly name
summary string? A short description for this package
thumb string? A URL to this package's thumbnail
packageType PackageType The package's type
updated long UNIX timestamp for when the package was last updated
description string? A longer description for this package
background string? A URL to this package's in-game background
download DownloadInfo Download information for this package
config Config? Map & player count config for this package
usersNow int Number of users currently playing
usersMonth int Number of users that played this month
usersTotal int Number of users that have ever played
tags string[] A list of tags that describe this gamemode.

MenuPackage

These are used in the menu (search, "trending", etc) to show a package without loading all of its data.

Name Type Description
org Org The organisation owning this package
ident string This package's identifier
title string This package's human-friendly name
summary string? A short description for this package
thumb string? A URL to this package's thumbnail
packageType PackageType The package's type
updated long UNIX timestamp for when the package was last updated
usersNow int Number of users currently playing
usersMonth int Number of users that played this month
usersTotal int Number of users that have ever played
tags string[] A list of tags that describe this gamemode.

Org

These are used in various places and are used to describe organisations.

Name Type Description
ident string This organisation's identifier
title string This organisation's human-friendly name
description string? This organisation's description
thumb string? A URL to the organisation's chosen thumbnail
socialTwitter string? A URL to the organisation's Twitter account
socialWeb string? A URL to the organisation's website

Config

These are used to provide the game with info about how a gamemode should be set up.

Name Type Description
showMapSelect bool Show the map select screen?
defaultMap string Default map
minPlayers int Minimum number of maxplayers
maxPlayers int Maximum number of maxplayers
clientDownloadShared bool Client downloads gamemode?

Endpoints

GET /sbox/asset/get

Params

id: An identifier (org.package) for the asset you wish to retrieve info about.

Returns

An Asset

Example Request

/sbox/asset/get?id=facepunch.pool

Example Response

{ "Asset": { "Org": { "Ident": "facepunch", "Title": "Facepunch", "Description": "", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/logo.1.png", "SocialTwitter": "", "SocialWeb": "" }, "Ident": "pool", "Title": "Pool", "Summary": "A classic pub game where your skill is determined by your blood-alcohol content.\r\n", "Description": "A classic pub game where your skill is determined by your blood-alcohol content.\r\n", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/pool/thumb.b52e5af8.jpg", "Background": "https://files.facepunch.com/sbox/org/facepunch/pool/background.21884981.jpg", "PackageType": 2, "Updated": 1619706156, "Download": { "Type": "github", "Url": "https://github.com/Facepunch/sbox-pool/tree/master" }, "Config": { "ShowMapSelect": false, "DefaultMap": "pool_lounge_v2", "MinPlayers": 2, "MaxPlayers": 2, "ClientDownloadShared": true }, "UsersNow": 0, "UsersDay": 3, "UsersMonth": 70, "UsersTotal": 235, "Tags": [ "!mousekeyboard", "multiplayer", "mousekeyboard" ] } }

GET /sbox/asset/list

Params

type: map or gamemode.

order: trending, popular, newest, live. Defaults to trending.

search: Any search query.

category (An Index Value starting at 1):

Index Sort-By
1 SandBox
2 Tech Demo/Expermental
3 Sports
4 Shooting
5 Parkour
6 Social
7 Meme
8 Roleplay
9 Racing
10 Mystery
11 Survival
12 Animals
13 Food
14 Strategy
15 Space
16 Fighting
17 Retro
18 Music
19 Art
20 Tycoon

Returns

A list of Packages.

Example Request

/sbox/asset/list?type=map&order=trending&search=Construct

Example Response

[ { "Org": { "Ident": "facepunch", "Title": "Facepunch" }, "Ident": "construct", "Title": "Construct", "Summary": "A simple construct map", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/construct/thumb.2f5f6e0a.jpg", "PackageType": 1, "Updated": 1620642104, "UsersNow": 1, "UsersDay": 42, "UsersMonth": 357, "UsersTotal": 480, "Tags": [] }, { "Org": { "Ident": "phar", "Title": "phar0" }, "Ident": "construct_racing", "Title": "Construct Race Edition BETA", "Summary": "Construct but in Race track form. Fast compile for now.", "Thumb": "https://files.facepunch.com/sbox/org/phar/construct_racing/thumb.32093d46.jpg", "PackageType": 1, "Updated": 1626114531, "UsersNow": 0, "UsersDay": 1, "UsersMonth": 19, "UsersTotal": 19, "Tags": [] } ]

Other

Finding an Org

There's no known endpoint for organizations. This is the closest you can get:

  1. Visit several endpoints (/asset/find?type={map}|{gamemode}, /menu/index) and collect a list of orgs with their gamemode idents
  2. Search that list for an org that matches the ident we're looking for
  3. Visit /asset/get?id={org}.{ident}
  4. Get the title & description for the org from this

Player Counts

Player accounts appear to use the Steam Lobby API; this means that an active Steam instance is required, using an account with access to s&box.

To enumerate through lobbies, use Steamworks.SteamMatchmaking.LobbyList.

Special Pages


Wikis

?

Render Time: 17ms

DB GetPage 1
Generate Html 3
SaveChanges (1) 6
Render Body 0
Render Sidebar 2