<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. # 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 | ## Find Result⤶ ## FindResult⤶ This is returned by `/sbox/asset/find` and is used to enumerate search results. |Name |Type |Description | |---------------|----------------|----------------------------------------------|⤶ | type | `PackageType` | The package types being returned | | assets | `Package[]` | A list of matching packages | ⤶ ## Category⤶ ⤶ This is returned by `/sbox/menu/index` and is used to describe a category displayed on the main menu.⤶ ⤶ |Name |Type |Description |⤶ |---------------|-------------|----------------------------------------------|⤶ | title | `string` | This category's title |⤶ | description | `string?` | This category's description |⤶ | packages | `Package[]` | A list of packages within this category |⤶ |Name |Type |Description | |---------------|-----------------|----------------------------------------------|⤶ | type | `PackageType` | The package types being returned | | assets | `MenuPackage[]` | A list of matching packages | ## 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](https://apix.facepunch.com/api/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.1.jpg", "background": "https://files.facepunch.com/sbox/org/facepunch/pool/background.1.jpg", "packageType": 2, "download": { "type": "github", "url": "https://github.com/Facepunch/sbox-pool/tree/main", },⤶ "updated": 1619706156⤶ } "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/find ### Params `type`: `map` or `gamemode`. `order`: `trending`, `popular`, `newest`. Defaults to `trending`. ### Returns A `FindResult` object. ### Example Request [/sbox/asset/find?type=map](http://apix.facepunch.com/api/sbox/asset/find?type=map) ### Example Response ``` { "type": 1, "order": "Newest",⤶ "assets": [ { "org": { "ident": "baks", "title": "bakscratch"⤶ }, "ident": "office", "title": "Workplace", "summary": "Remake of popular map; WIP just the interior.", "thumb": "https://files.facepunch.com/sbox/org/baks/office/thumb.4.jpg", "packageType": 1, "updated": 1619045983⤶ { "org": { "ident": "willow", "title": "The Willow Tree"⤶ }, "ident": "castlewhitespire", "title": "Castle Whitespire", "summary": "", "thumb": "https://files.facepunch.com/sbox/org/willow/castlewhitespire/thumb.ae38aca6.jpg", "packageType": 1, "updated": 1626638355,⤶ "usersNow": 0,⤶ "usersDay": 3,⤶ "usersMonth": 3,⤶ "usersTotal": 3,⤶ "tags": []⤶ },⤶ {⤶ "org": {⤶ "ident": "kote",⤶ "title": "KotE"⤶ }, { "org": { "ident": "exeros", "title": "Exeros"⤶ }, "ident": "floodgate", "title": "Flood Gate", "summary": "Flood map", "thumb": "https://files.facepunch.com/sbox/org/exeros/floodgate/thumb.2.jpg", "packageType": 1, "updated": 1619037397⤶ } "ident": "vice_city", "title": "Vice City", "summary": "Vice City", "thumb": "https://files.facepunch.com/sbox/org/kote/vice_city/thumb.9977f747.jpg",⤶ "packageType": 1, "updated": 1626557106, "usersNow": 0, "usersDay": 5, "usersMonth": 17, "usersTotal": 17, "tags": []⤶ } ] } ``` ## GET /sbox/asset/list ### Params `type`: `map` or `gamemode`. `order`: `trending`, `popular`, `newest`. Defaults to `trending`. `search`: Any search query. ### Returns A list of `Package`s. ### Example Request [/sbox/asset/list?type=map&order=trending&search=Construct](http://apix.facepunch.com/api/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, "usersMonth": 361, "usersTotal": 0⤶ "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, "usersMonth": 18, "usersTotal": 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](https://wiki.facepunch.com/steamworks/SteamMatchmaking.LobbyList).