Plugin RestAPI
This API provides a very simple RestAPI that you can use together with the WebService. You can use it to power the DCS Statistics Dasboard.
Configuration
As RestAPI is an optional plugin, you need to activate it in main.yaml first like so:
# config/main.yaml
opt_plugins:
- restapi
You can configure the RestAPI endpoints in your config\plugins\restapi.yaml like so:
# config/plugins/restapi.yaml
DEFAULT:
prefix: /stats # Optional: use this prefix (you can omit the leading / if you like)
auth:
api_key: "CHANGE_ME"
jwt:
key: "some-shared-token-key"
jwks_url: https://digitalkneeboardsimulator.com/api/pubkey # the URL of your JWKS
security:
# Defines which source networks are treated as "trusted".
# Trusted requests can use separate endpoint auth rules from remote requests.
# Loopback is always "local" and does not need to be listed here.
trusted:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- fc00::/7
# optional fallback if an endpoint has no explicit rule
default:
local: none # We do not need any auth when we connect through the loopback interface
trusted: api_key # We need an API key if we connect through trusted networks
remote: jwt # We need a JWT if we connect through the internet
# remote: disabled # You can also disable connections from specific networks at all like so.
endpoints: # endpoint configuration
servers: # /servers
security:
local: none
trusted: none
remote: api_key
filter: # config parameter (in this case, the server filter list)
- 'MyPrivateServer' # Do not show a server named "MyPrivateServer"
- '(.*)Private(.*)' # Do not show any server that has "Private" in its name
include_weather: true # Include weather information in /servers endpoint (default: true)
server_attendance: # /server_attendance
enabled: true # Enable the server attendance statistics endpoint (default: true)
security:
local: none
trusted: api_key
remote: jwt
Machine API v1 (/api/v1)
A second, versioned surface serves the action rows on a fixed /api/v1 prefix. It reads two keys:
# config/plugins/restapi.yaml
DEFAULT:
api_v1:
enabled: true # false mounts no /api/v1 route at all (default: true)
endpoints:
v1/servers: # the row's key is 'v1/' + its path without the leading slash
enabled: true # false leaves that one route unregistered
security:
local: api_key # optional: a policy may RAISE the class floor, never lower it
trusted: api_key
remote: jwt
v1/servers/{server_name}/start:
security:
remote: jwt
Important
security.default.local: none does not open a v1 write. The effective requirement is
max(class floor, configured policy), so a lifecycle route such as
POST /api/v1/servers/{server_name}/stop needs an API key even on loopback. Only read routes
run keyless. The legacy routes keep their configured behaviour.
A legacy endpoints key never governs a v1 row: /servers is servers on the legacy surface and
v1/servers here. A legacy key that spells a v1 row's path is reported with a WARNING at mount time.
The routes, the auth order, the floors and the response envelope are documented in
API Documentation.
Warning
Do NOT use a prefix if you work with the DCS Statistics Dasboard!
RestAPI
The following commands are available through the API. For detailed parameter definitions, response models, and schemas, see API Documentation.
| API | GET / POST | Parameters | Description |
|---|---|---|---|
| /airbase | GET | server_name: string, airbase_name: string | Get information for a given airbase on a given server. |
| /airbase/atis | GET | server_name: string, airbase_name: string | Get ATIS information for an airbase on a given server. |
| /airbase/capture | POST | server_name: string, airbase_name: string, coalition: int | Capture the airbase. |
| /airbase/warehouse | GET | server_name: string, airbase_name: string | Get warehouse information for an airbase on a given server. |
| /airbase/warehouse/item | POST | server_name: string, airbase_name: string, item: string, value: int | Set warehouse item quantity for an airbase on a given server. |
| /airbases | GET | server_name: string | Get a listing of all airbases on a given server. |
| /convertCoordinates | GET | server_name: string, coordinates: string | Convert provided coordinate string into other formats. |
| /credits | POST | nick: string, [date: string | None], [campaign: string |
| /current_server | GET | nick: string, [date: string | None] |
| /events | GET | ucid: string, start_time: datetime, end_time: datetime, [event: string | None], [init_type: string |
| /getuser | POST | [nick: string], [discord_id: string] | Get users by name |
| /greenieboard | POST | [date: string | None], [server_name: string |
| /highscore | GET | [server_name: string], [period: string], [limit: int] | Get highscore statistics for players |
| /instance/mission/load | POST | server_name: string, mission_name: string | Load a mission on a given server. |
| /instance/mission/pause | POST | server_name: string | Pause the mission on a given server. |
| /instance/mission/restart | POST | server_name: string, [run_extensions: bool], [use_orig: bool], [when_empty: bool] | Restart the mission on a given server. |
| /instance/mission/unpause | POST | server_name: string | Unpause the mission on a given server. |
| /instance/missions | GET | server_name: string | Return all missions for a given server. |
| /instance/restart | POST | server_name: string | Restart a server. |
| /instance/shutdown | POST | server_name: string, [force: bool], [maintenance: bool], [when_empty: bool] | Shut a server down (terminates the DCS process). |
| /instance/start | POST | server_name: string | Start a server. |
| /instance/stop | POST | server_name: string | Stop a server. |
| /leaderboard | GET | what: string, [order: string], [query: string | None], [limit: int |
| /linkme | POST | discord_id: string, [force: bool] | Link your Discord account to your DCS account |
| /mission/bullseyes | GET | server_name: string | Get the bullseye coordinates for blue and red coalitions in the current mission. |
| /mission/drawings | GET | server_name: string | Get mission drawing objects grouped by drawing layer. |
| /mission/group | GET | server_name: string, coalition: string, group_name: string, [group_type: string | None] |
| /mission/group/waypoints | GET | server_name: string, group_name: string, group_type: string | Get the lat/lon waypoints for a named group in the current mission. |
| /mission/groups | GET | server_name: string, coalition: string, [group_type: string | None] |
| /mission/unit | GET | server_name: string, unit_name: string | Get mission unit data including current position, loadout, navaids, and waypoints. |
| /mission/upload | POST | server_name: string, file: string, filename: string, load_after: bool | Upload a .miz mission file to the server. |
| /modulestats | POST | nick: string, [date: string | None], [server_name: string |
| /node/restart | POST | [node_name: string | None], [force: bool] |
| /player_info | POST | nick: string, [date: string | None], [server_name: string |
| /player_squadrons | POST | nick: string, [date: string | None] |
| /refuelings | GET | ucid: string, [module: string | None], [tanker: string |
| /server_attendance | GET | [server_name: string] | Get detailed server attendance statistics |
| /servers | GET | [server_name: string | None] |
| /serverstats | GET | [server_name: string] | List the statistics of a whole group |
| /squadron_credits | POST | name: string, [campaign: string] | Squadron campaign credits |
| /squadron_members | POST | name: string | List squadron members |
| /squadrons | GET | [limit: int], [offset: int] | List all squadrons and their roles |
| /stats | POST | nick: string, [date: string | None], [server_name: string |
| /topkdr | GET | [limit: int], [offset: int], [server_name: string] | Get top KDR statistics for players |
| /topkills | GET | [limit: int], [offset: int], [server_name: string] | Get top kills statistics for players |
| /traps | POST | nick: string, [date: string | None], [limit: int |
| /traps/img | GET | trap_id: int | Get trap image for a player |
| /trueskill | GET | [limit: int], [offset: int], [server_name: string] | Get TrueSkill:tm: statistics for players |
| /weaponpk | POST | nick: string, [date: string | None], [server_name: string |
Note
To get more detailled API documentation with test options, please enable debug in your WebService config and access https://localhost:9876/docs.
New Features
Weather Information
The /servers endpoint now includes real-time weather data for running DCS servers:
{
"weather": {
"temperature": 16.0,
"wind_speed": 0.968,
"wind_direction": 290,
"pressure": 765.0,
"visibility": 5000,
"clouds_base": 0,
"clouds_density": 0,
"precipitation": 0,
"fog_enabled": false,
"dust_enabled": false
}
}
Server Attendance Statistics
The /server_attendance endpoint provides comprehensive server attendance analytics:
- Server attendance statistics: Current active players, unique players, total playtime hours, and Discord member engagement for different time periods (24h, 7d, 30d)
- Top statistics: Most popular theatres, missions, and modules by playtime and usage
- Daily trends: Daily unique player counts for the last 7 days to analyze server activity patterns
- Combat statistics: Total sorties, kills, deaths, and PvP statistics from mv_serverstats
Global statistics (no parameters):
GET /server_attendance
Server-specific statistics (using DCS server name):
GET /server_attendance?server_name=VEAF (www.veaf.org) [fr] - Private Foothold 2
Server-specific statistics (using instance alias):
GET /server_attendance?server_name=foothold2_server
Response example:
{
"current_players": 8,
"unique_players_24h": 15,
"total_playtime_hours_24h": 45.5,
"discord_members_24h": 12,
"unique_players_7d": 35,
"total_playtime_hours_7d": 180.2,
"discord_members_7d": 28,
"unique_players_30d": 85,
"total_playtime_hours_30d": 720.8,
"discord_members_30d": 65,
"daily_trend": [
{"date": "2025-12-24", "unique_players": 15},
{"date": "2025-12-25", "unique_players": 18}
]
}
Server Name Resolution
All endpoints that accept a server_name parameter now support both server naming conventions seamlessly:
- Instance alias: foothold2_server (from nodes.yaml configuration)
- DCS server name: VEAF (www.veaf.org) [fr] - Private Foothold 2 (from servers.yaml configuration)
The resolution is handled transparently by the get_resolved_server() method, which:
1. Checks if the provided name is already a full DCS server name
2. If not, searches instance aliases and returns the corresponding DCS server name
3. Returns both the resolved name and server object for use in endpoints
This approach ensures consistent behavior across all endpoints while maintaining simple, readable SQL construction patterns.
Configuration reference
| Key | Type | Description | Example |
|---|---|---|---|
DEFAULT |
map | Default RestAPI settings applied to all servers. | prefix: /stats |
DEFAULT
| Key | Type | Description | Example |
|---|---|---|---|
DEFAULT.prefix |
str | Optional URL prefix prepended to every endpoint. | /stats |
DEFAULT.auth |
map | |
|
DEFAULT.auth.api_key |
text | API key that clients must send in the X-API-Key header. | CHANGE_ME |
DEFAULT.auth.jwt |
map | JWT settings used to verify bearer tokens. | key: some-shared-token-key |
DEFAULT.auth.jwt.key |
text | Shared key a valid JWT must carry to be accepted. | some-shared-token-key |
DEFAULT.auth.jwt.jwks_url |
url | URL of the JWKS used to verify JWT signatures. | https://digitalkneeboardsimulator.com/api/pubkey |
DEFAULT.security |
map | |
|
DEFAULT.security.trusted |
list | Source networks that are treated as trusted. | - 10.0.0.0/8 |
DEFAULT.security.default |
map | Fallback auth rule for endpoints without their own. | local: none |
DEFAULT.security.default.local |
str | Auth required for loopback (local) requests. (one of: none, api_key, jwt, disabled) | none |
DEFAULT.security.default.trusted |
str | Auth required for requests from trusted networks. (one of: none, api_key, jwt, disabled) | api_key |
DEFAULT.security.default.remote |
str | Auth required for requests from the internet. (one of: none, api_key, jwt, disabled) | jwt |
DEFAULT.endpoints |
map | |
|
DEFAULT.endpoints.<(.+)> |
map | |
|
DEFAULT.endpoints.<(.+)>.enabled |
bool | Enable or disable this API endpoint. | true |
DEFAULT.endpoints.<(.+)>.security |
map | Per-scope auth rules for this endpoint. | local: none |
DEFAULT.endpoints.<(.+)>.security.local |
str | Auth required for loopback (local) requests. (one of: none, api_key, jwt, disabled) | none |
DEFAULT.endpoints.<(.+)>.security.trusted |
str | Auth required for requests from trusted networks. (one of: none, api_key, jwt, disabled) | api_key |
DEFAULT.endpoints.<(.+)>.security.remote |
str | Auth required for requests from the internet. (one of: none, api_key, jwt, disabled) | jwt |