AI Data Collection

Overview

The SARD AI Data Collection API allows the game server to submit game event logs and gameplay telemetry to SARD for AI-powered processing.

This data is used to improve cheat detection, behavioral analysis, anomaly detection, and investigation workflows. Unlike the Validation API, which confirms whether a player is running SARD correctly, the AI Data Collection API receives authoritative gameplay data from your backend.

Purpose

Game servers have access to authoritative gameplay events that cannot always be observed from the client side. Sending these events to SARD helps provide a more complete view of player behavior.

Typical examples include:

• Player connection and disconnection events
• Match start and match end events
• Kill, death, assist, and damage events
• Movement, position, or speed-related records
• Inventory, item pickup, item drop, or trade events
• Economy, reward, or transaction events
• Suspicious gameplay actions detected by the game server
• Custom anti-cheat signals generated by the game backend

The submitted data can be processed by SARD AI systems to identify suspicious patterns, correlate server-side behavior with client-side protection data, and support investigation or enforcement decisions.

Data collection flow

The integration works in the following way:

1. A gameplay event occurs on the game server.
2. The game server formats the event data as JSON.
3. The game server sends the data to the SARD AI Data Collection API.
4. SARD receives and stores the event data for AI processing.
5. SARD analysis systems process the submitted data together with other available anti-cheat signals.

Recommended flow:

Game Client
    |
    | gameplay action
    v
Game Server
    |
    | server-side event log
    v
SARD AI Data Collection API
    |
    | AI processing
    v
SARD Analysis / Detection Systems

API credentials

API credentials are available in the SARD Admin portal.

The integration screen provides:

Field	Description
URL	The API endpoint assigned to your environment. The numeric value in the path is the game ID from the Admin portal.
Token	Authorization token used by the game server.
Data	Example JSON payload format.

Example:

URL:   https://data.ru.sard.ac/api/<GAME_ID>
Token: <provided in SARD Admin portal>
Data:  {"data":"@any_data"}

<GAME_ID> is the game ID provided in the Admin portal. Use the URL and token provided for your game.

Request format

The game server should send an HTTP POST request to the provided endpoint.

Sample request

curl -X POST https://data.ru.sard.ac/api/<GAME_ID> \
  -H "Authorization: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "event": "player_kill",
      "timestamp": "2026-05-27T12:00:00Z",
      "match_id": "match-12345",
      "server_id": "server-eu-01",
      "player_id": "player-001",
      "target_player_id": "player-002",
      "weapon": "rifle",
      "position": {
        "x": 120.5,
        "y": 44.0,
        "z": -18.2
      }
    }
  }'

Payload structure

The API accepts a JSON object with a data field.

{
  "data": {
    "event": "player_kill",
    "timestamp": "2026-05-27T12:00:00Z",
    "match_id": "match-12345",
    "player_id": "player-001"
  }
}

The data object can contain any game-specific event fields required for analysis.

Recommended common fields:

Field	Description
event	Event name or event type.
timestamp	Time when the event occurred, preferably in UTC.
player_id	Unique player identifier used by the game.
match_id	Match, session, or room identifier.
server_id	Game server identifier.
map	Map, level, or world identifier.
game_mode	Game mode or queue type.
metadata	Additional game-specific event details.

Event design recommendations

For best AI processing results, submit events in a consistent structure.

Recommended practices:

• Use stable event names, for example player_kill, match_started, or item_pickup.
• Use UTC timestamps in ISO 8601 format.
• Use the same player identifier that is used in SARD integration where possible.
• Include match, server, and game mode context when available.
• Avoid changing field names between game versions unless required.
• Send raw factual event data instead of pre-interpreted conclusions.
• Include enough context for the event to be useful during investigation.

Example event types

Player connection

{
  "data": {
    "event": "player_connected",
    "timestamp": "2026-05-27T12:00:00Z",
    "player_id": "player-001",
    "server_id": "server-eu-01",
    "ip_region": "EU",
    "game_version": "1.24.0"
  }
}

Match result

{
  "data": {
    "event": "match_finished",
    "timestamp": "2026-05-27T12:35:00Z",
    "match_id": "match-12345",
    "server_id": "server-eu-01",
    "map": "arena_01",
    "game_mode": "ranked",
    "duration_seconds": 2100,
    "players": [
      {
        "player_id": "player-001",
        "team": "blue",
        "kills": 18,
        "deaths": 4,
        "assists": 7,
        "score": 2450
      }
    ]
  }
}

Suspicious server-side action

{
  "data": {
    "event": "server_suspicious_action",
    "timestamp": "2026-05-27T12:10:30Z",
    "match_id": "match-12345",
    "player_id": "player-001",
    "reason": "movement_speed_exceeded",
    "observed_speed": 18.4,
    "expected_max_speed": 9.5,
    "position": {
      "x": 320.1,
      "y": 12.0,
      "z": -44.8
    }
  }
}

Security requirements

The AI Data Collection API token must be used only from trusted backend services.

Do not:

• Include the token in the game client.
• Expose the token in public repositories.
• Send requests directly from player devices.
• Share the token between unrelated environments.

Recommended:

• Store the token in server-side configuration or secret storage.
• Use separate credentials for production and test environments when available.
• Rotate the token if it may have been exposed.
• Restrict outbound API access to trusted game backend services.

Important notes

• The API is intended for server-side data submission only.
• Submitted data should not contain unnecessary personal information.
• Event data should be sent as close to real time as possible.
• Temporary network failures should be retried by the game backend.
• High-volume events should be batched or filtered according to guidance from SARD.

Summary

The AI Data Collection API provides SARD with authoritative game-server event data for AI analysis.

By sending structured gameplay logs from the game server, partners can improve detection quality, support investigations, and give SARD a stronger server-side signal for identifying suspicious behavior.