Revision Difference
Backend_API#546575
<cat>Dev.Backend</cat>
<warning>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.</warning>
This page is an analysis of the API used for the [dev site](https://sbox.facepunch.com/dev/) 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'`).⤶
This page is an analysis of the API used for the [dev site](https://sbox.facepunch.com/dev/) 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/` domain.
# 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⤶
## DownloadInfo (legacy)⤶
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⤶
⤶
## 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. |
| 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 |
| ConfigJson | `string?` | A serialized json string containing info for lobbies |
| 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 |
| UsersDay | `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. |⤶
| CategoryId | `int` | A list of tags that describe this gamemode. |⤶
| SubCategoryId | `int` | A list of tags that describe this gamemode. |⤶
| Version | `Version?` | A list of tags that describe this gamemode. |⤶
| Favourited | `int` | A list of tags that describe this gamemode. |⤶
| VotesUp | `int` | A list of tags that describe this gamemode. |⤶
| VotesDown | `int` | A list of tags that describe this gamemode. |⤶
| Source | `string` | A list of tags that describe this gamemode. |⤶
⤶
## Version⤶
⤶
An object containing info about how the game should fetch assets through the new download system.⤶
⤶
|Name |Type |Description |⤶
|----------------------|----------|--------------------------------------------------------------|⤶
| FileCount | `int` | Number of files |⤶
| TotalSize | `int` | Total game size in bytes |⤶
| AssetVersionId | `int` | This version's ID |⤶
| Created | `string` | The timestamp for when this version was created |⤶
| Manifest | `string` | A serialized json string containing a list this game's files |⤶
## 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⤶
⤶
## 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 /sandbox-asset
### Params
`id`: An identifier (`org`.`package`) for the asset you wish to retrieve info about.
### Returns
An `Asset`
### Example Request
[/sandbox-asset?id=facepunch.pool](https://apix.facepunch.com/sandbox-asset?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"⤶
]⤶
}⤶
"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"
},
"ConfigJson": "{\"MinPlayers\":1,\"MaxPlayers\":2,\"NetworkType\":0,\"MapList\":[\"pool_lounge_v2\"],\"MapSelection\":1,\"RankType\":1,\"LeaderboardType\":1}",
"UsersNow": 0,
"UsersDay": 4,
"UsersMonth": 55,
"UsersTotal": 2191,
"Tags": [⤶
"!mousekeyboard",
"multiplayer",
"mousekeyboard"⤶
],
"CategoryId": 3,
"SubCategoryId": 0,⤶
"Version": null,
"Favourited": 65,
"VotesUp": 87,⤶
"VotesDown": 2,⤶
"Source": "https://github.com/Facepunch/sbox-pool/tree/master"⤶
}⤶
}
```
---
⤶
⤶
## GET /sandbox-asset-list⤶
⤶
## GET /sandbox-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 | Category |
|:-------:|:---------------------:|
|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 |
|21 | Streamer |⤶
### Returns
A list of `Package`s.
### Example Request
[/sandbox-asset-list?type=map&order=trending&search=Construct](http://apix.facepunch.com/sandbox-asset-list?type=map&order=trending&search=Construct)
### Example Response
```
[
{
"Org": {
"Ident": "facepunch",
"Title": "Facepunch"⤶
{
"Org": {
"Ident": "facepunch",
"Title": "Facepunch",⤶
"Thumb": "https://files.facepunch.com/sbox/org/facepunch/logo.1.png"⤶
},⤶
"Ident": "construct",⤶
"Title": "Construct",⤶
"Summary": "A simple construct map",⤶
"Description": "This is the default map. It both has purpose and no purpose.",⤶
"Thumb": "https://files.facepunch.com/sbox/org/facepunch/construct/thumb.2f5f6e0a.jpg",⤶
"PackageType": 1,⤶
"Updated": 1643893793,⤶
"UsersNow": 0,⤶
"UsersDay": 134,⤶
"UsersMonth": 1580,⤶
"UsersTotal": 7774,⤶
"Tags": [],⤶
"CategoryId": 0,⤶
"SubCategoryId": 0,⤶
"Favourited": 0,⤶
"VotesUp": 0,⤶
"VotesDown": 0,⤶
"Source": null⤶
},
"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": []⤶
}⤶
{
"Org": {
"Ident": "cstruct",
"Title": "egg corporation's things",
"Thumb": ""⤶
},
"Ident": "gm_construct",
"Title": "gm construct",
"Summary": "Bad port, but is working port!",
"Description": "A bad port of gm_construct v13, that I am trying to get fixed-ish. I fully expect someone else to come along and do it better than I can, and if you have a problem with this version I encourage you to make your own. I'll give you all the files if you ask.\r\n\r\nVERSION HISTORY:\r\nV1 Release\r\nV1.1 Fixed some weird white sprites and also added some basic baked lighting(dark room now dark again)\r\nV1.1.1 Ladder for secret room works now. It's literally a stack of clipbrushes, basically very narrow invisible stairs, but that might unironically be better than Source 1 ladders, lmao\r\nV1.2 Added Long Description into map, this is now a \"cool release\" until I get the urge to work on it more. Contact me if it breaks, if you can.",
"Thumb": "https://files.facepunch.com/sbox/org/cstruct/gm_construct/thumb.3464c8e.jpg",⤶
"PackageType": 1,
"Updated": 1630804910,
"UsersNow": 0,
"UsersDay": 3,
"UsersMonth": 102,⤶
"UsersTotal": 1458,
"Tags": [],
"CategoryId": 0,
"SubCategoryId": 0,
"Favourited": 0,
"VotesUp": 0,
"VotesDown": 0,
"Source": null⤶
}
]
```
# 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](https://wiki.facepunch.com/steamworks/SteamMatchmaking.LobbyList).
⤶
Garry's Mod
Rust
Steamworks
Wiki Help
S&box