Skip to content

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
auth:
api_key: CHANGE_ME
security:
remote: jwt

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
jwks_url: https://digitalkneeboardsimulator.com/api/pubkey
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
- 192.168.0.0/16
DEFAULT.security.default map Fallback auth rule for endpoints without their own. local: none
trusted: api_key
remote: jwt
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
trusted: api_key
remote: jwt
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