Unofficial Helldivers 1 API Documentation

by XTC

This is external reference material documenting the official Helldivers 1 API at api.helldiversgame.com. It is not part of the helldivers.bot API. For the helldivers.bot API, see API Reference.

General Infrastructure

There are two servers the client connects to:

api.helldiversgame.com — global stats, events, and battlefield data
helldivers.api.wwsga.me — userdata (do not connect to this server)

graph LR
    subgraph Official["OFFICIAL HELLDIVERS 1 API"]
        EP["api.helldiversgame.com/1.0/"]
    end

    subgraph Actions["AVAILABLE ACTIONS"]
        CS["get_campaign_status<br/><small>Live war state + stats</small>"]
        SN["get_snapshots<br/><small>Historical time-series</small>"]
        UN["get_usernames<br/><small>Steam/PSN player names</small>"]
        LB["get_leaderboards<br/><small>Player rankings</small>"]
        AE["get_available_entitlements<br/><small>DLC data</small>"]
    end

    CLIENT["HTTPS POST<br/><small>action=...</small>"] --> EP
    EP --> CS
    EP --> SN
    EP --> UN
    EP --> LB
    EP --> AE

    style Official fill:#1c1917,stroke:#f59e0b,color:#fbbf24
    style Actions fill:#1e293b,stroke:#3b82f6,color:#60a5fa

The client uses libcurl with SSL. Certificate pinning may be in use.

Global statistics are available via HTTPS POST to https://api.helldiversgame.com/1.0/.

If no POST parameters are given, the server returns:

{"time": <unix_time>, "error_code": 1, "error_message": "No action set"}

Valid action POST parameter values:

get_campaign_status
get_usernames
get_available_entitlements
get_snapshots
get_leaderboards

get_campaign_status

Returns the current war state including campaign progress, events, and statistics.

Response structure:

Key	Value
`time`	Unix timestamp of request
`error_code`	`0`
`campaign_status`	Array of faction status objects (see below)
`defend_event`	Current/most recent defense event object
`attack_events`	Array of homeworld assault objects (one per faction)
`statistics`	Array of global stats objects (one per faction)

graph TD
    RESP["API Response"] --> TIME["time<br/><small>Unix timestamp</small>"]
    RESP --> ERR["error_code<br/><small>0 = success</small>"]
    RESP --> CS["campaign_status[]<br/><small>3 factions</small>"]
    RESP --> DE["defend_event<br/><small>Single object or null</small>"]
    RESP --> AE["attack_events[]<br/><small>3 factions</small>"]
    RESP --> STATS["statistics[]<br/><small>3 factions</small>"]

    CS --> F0["[0] Bugs"]
    CS --> F1["[1] Cyborgs"]
    CS --> F2["[2] Illuminate"]

    style RESP fill:#1e293b,stroke:#3b82f6,color:#60a5fa
    style CS fill:#0f1a0f,stroke:#22c55e,color:#4ade80
    style DE fill:#1c1917,stroke:#f59e0b,color:#fbbf24
    style AE fill:#1c1917,stroke:#f59e0b,color:#fbbf24
    style STATS fill:#1a1a2e,stroke:#a855f7,color:#c084fc

campaign_status

Array of 3 objects ordered by faction: index 0 = Bugs, 1 = Cyborgs, 2 = Illuminate.

Key	Data Type	Value
`season`	number	Season / War number
`points`	number	Current influence points (decreases over time)
`points_taken`	number	Total influence points gained by players
`points_max`	number	Points required to trigger a homeworld assault event
`status`	string	`'active'`, `'defeated'`, or `'hidden'`
`introduction_order`	number	Order in which faction was introduced to the war (255 if not yet introduced)

defend_event

Single object for the most recent or currently active defense event.

Key	Data Type	Value
`season`	number	Season / War number
`event_id`	number	Defense event ID
`start_time`	number	Unix timestamp of event start
`end_time`	number	Unix timestamp of event deadline
`region`	number	ID of the region containing the defended planet
`enemy`	number	Enemy faction ID (0=Bugs, 1=Cyborgs, 2=Illuminate)
`points`	number	Current influence points gained
`points_max`	number	Points needed for the defense to succeed
`status`	string	`'active'`, `'success'`, or `'failure'`

attack_events

Array of 3 objects (one per faction) for the most recent homeworld assault of each faction.

Key	Data Type	Value
`season`	number	Season / War number
`event_id`	number	Attack event ID
`start_time`	number	Unix timestamp of event start
`end_time`	number	Unix timestamp of event deadline
`enemy`	number	Enemy faction ID
`points`	number	Current influence points gained
`points_max`	number	Points needed for the assault to succeed
`status`	string	`'active'`, `'success'`, or `'failure'`
`players_at_start`	number	Players in mission when the event started
`max_event_id`	number	Same as `event_id` (purpose unclear)

statistics

Array of 3 objects (one per faction). Sum all three for global totals.

Key	Data Type	Value
`season`	number	Season / War number
`season_duration`	number	Seconds the current war has been going
`enemy`	number	Enemy faction ID
`players`	number	Players currently online
`total_unique_players`	number	Unique players this season
`missions`	number	Total missions played
`successful_missions`	number	Successful missions
`total_mission_difficulty`	number	Sum of difficulty of successful missions
`completed_planets`	number	Planets where all missions were completed
`defend_events`	number	Total defend events
`successful_defend_events`	number	Successful defend events
`attack_events`	number	Total homeworld assaults
`successful_attack_events`	number	Successful homeworld assaults
`deaths`	number	Player deaths
`accidentals`	number	Player-caused deaths (friendly fire)
`shots`	number	Shots fired
`hits`	number	Shots hit
`kills`	number	Enemies killed

get_usernames

POST parameters:

Key	Value
`action`	`'get_usernames'`
`network`	`'steam'` (PC) or `'psn'` (PlayStation)
`count`	Number of users to retrieve

Response:

Key	Data Type	Value
`time`	number	Unix timestamp
`error_code`	number	`0`
`usernames`	Array	Array of user identifiers

For network: 'steam', the array contains hex Steam IDs. For network: 'psn', it contains PSN usernames.

get_available_entitlements

DLC availability (details undocumented).

get_snapshots

Historical war data for a specific season.

POST parameters:

Key	Value
`action`	`'get_snapshots'`
`season`	Season number to retrieve

Response:

Key	Data Type	Value
`time`	number	Unix timestamp
`error_code`	number	`0`
`introduction_order`	Array	3 numbers showing faction introduction order (0/1/2 or 255)
`points_max`	Array	Points needed per faction to trigger homeworld assault
`snapshots`	Array	Time-series data points
`defend_events`	Array	Completed defense events
`attack_events`	Array	Completed homeworld assaults

snapshots

Each snapshot object has season (number), time (Unix timestamp), and data (stringified JSON array of 3 objects):

Key	Data Type	Value
`points`	number	Points needed for homeworld assault
`points_taken`	number	Points players have gained
`status`	string	`'hidden'`, `'active'`, `'success'`, or `'fail'`

defend_events / attack_events

Same structure as defend_event / attack_events in get_campaign_status, but with status values limited to 'success' or 'fail' (only completed events).

get_leaderboards

POST parameters:

Key	Value
`action`	`'get_leaderboards'`
`network`	`'steam'` or `'psn'`
`season`	Season number

Optional parameters:

Key	Value
`count`	Number of users to retrieve
`users`	Array of Steam IDs to filter

Response:

Key	Data Type	Value
`time`	number	Unix timestamp
`error_code`	number	`0`
`leaderboards`	Array	4 arrays: Bugs, Cyborgs, Illuminate, Global
`user_leaderboards`	Array	Filtered leaderboard data (only if `users` provided)

Leaderboard entry

Key	Data Type	Value
`online_id`	string	Steam ID (hex) or PSN username
`playtime`	number	Playtime in seconds
`planets`	number	Liberated planets
`score`	number	Community points
`player_xp`	number	Experience points

Sample Responses

get_campaign_status

{
    "time": 1774438558,
    "error_code": 0,
    "campaign_status": [
        {
            "season": 156,
            "points": 170123,
            "points_taken": 387515,
            "points_max": 543480,
            "status": "active",
            "introduction_order": 0
        },
        {
            "season": 156,
            "points": 176310,
            "points_taken": 260874,
            "points_max": 352100,
            "status": "active",
            "introduction_order": 1
        },
        {
            "season": 156,
            "points": 166514,
            "points_taken": 115874,
            "points_max": 253200,
            "status": "active",
            "introduction_order": 2
        }
    ],
    "defend_event": {
        "season": 156,
        "event_id": 4888,
        "start_time": 1774425902,
        "end_time": 1774433161,
        "region": 5,
        "enemy": 1,
        "points_max": 502,
        "points": 502,
        "status": "success"
    },
    "attack_events": [
        {
            "season": 155,
            "event_id": 915,
            "start_time": 1772992682,
            "end_time": 1773165482,
            "enemy": 0,
            "points_max": 44933,
            "points": 22592,
            "status": "fail",
            "players_at_start": 331,
            "max_event_id": 915
        },
        {
            "season": 156,
            "event_id": 916,
            "start_time": 1774216801,
            "end_time": 1774389601,
            "enemy": 1,
            "points_max": 35014,
            "points": 19611,
            "status": "fail",
            "players_at_start": 378,
            "max_event_id": 916
        },
        {
            "season": 155,
            "event_id": 907,
            "start_time": 1769891101,
            "end_time": 1770063901,
            "enemy": 2,
            "points_max": 35795,
            "points": 15931,
            "status": "fail",
            "players_at_start": 300,
            "max_event_id": 907
        }
    ],
    "statistics": [
        {
            "season": 156,
            "season_duration": 1261959,
            "enemy": 0,
            "players": 88,
            "total_unique_players": 14544,
            "missions": 94795,
            "successful_missions": 58952,
            "total_mission_difficulty": 283978,
            "completed_planets": 20589,
            "defend_events": 13,
            "successful_defend_events": 4,
            "attack_events": 1,
            "successful_attack_events": 0,
            "deaths": 368138,
            "kills": 19327247,
            "accidentals": 90764,
            "shots": 87879653,
            "hits": 40746802
        }
    ]
}

get_snapshots (season 1)

{
    "time": 1774438591,
    "error_code": 0,
    "introduction_order": [2, 1, 0],
    "points_max": [30000, 30000, 30000],
    "snapshots": [
        {
            "season": 1,
            "time": 1424881142,
            "data": "[{\"points\":1500,\"points_taken\":0,\"status\":\"hidden\"},{\"points\":1500,\"points_taken\":0,\"status\":\"hidden\"},{\"points\":1500,\"points_taken\":0,\"status\":\"active\"}]"
        }
    ],
    "defend_events": [
        {
            "season": 1,
            "event_id": 1,
            "start_time": 1424881201,
            "end_time": 1424881321,
            "region": 5,
            "enemy": 2,
            "points_max": 48,
            "points": 48,
            "status": "success",
            "players_at_start": 1
        }
    ],
    "attack_events": [
        {
            "season": 1,
            "event_id": 1,
            "start_time": 1425099481,
            "end_time": 1425272281,
            "enemy": 0,
            "points_max": 17960,
            "points": 1265,
            "status": "success",
            "players_at_start": 1
        }
    ]
}

Disclaimer

The Helldivers API servers and the entire API are not intended for third-party use. The writers behind this documentation do not take responsibility for legal action taken against the usage of the API.