Rebroadcast API

Endpoint reference for the Helldivers Bot API. All responses follow a standard envelope with time, code, message, and data / error fields.

Response Envelopes

Standard Envelope

Used by /api/healthcheck, /api/h1/campaign, /api/h1/update. The time field is elapsed milliseconds (floating-point). The message field is derived from the HTTP status code.

// Success
{ "time": 42.5, "code": 200, "message": "OK", "data": { ... } }

// Error
{ "time": 42.5, "code": 400, "message": "Bad Request", "error": "details" }

Rebroadcast Envelope

Used by /api/h1/rebroadcast error paths only. Mirrors the official HD1 API error format so proxy clients don't need to detect the error source. Successful rebroadcast responses return raw JSON directly.

{ "time": 1711234567, "error_code": 0, "error_message": "Invalid Content Type" }

Authentication

/api/h1/rebroadcast requires an API key via Authorization: Bearer <key>. Keys are managed from the user dashboard. /api/h1/update is internal (worker-only, Bearer token must match UPDATE_KEY). All other endpoints are public.

Endpoints

get/api/h1/campaign— Get campaign data for a specific season or the latest.

Returns campaign data for a given season if the `season` query parameter is provided and valid. If no season is provided, returns the latest campaign data. If data is not found locally, attempts to fetch and update from a remote source.

Parameters

Name	In	Type	Required	Description
season	query	string	no	The season number to fetch campaign data for.

Responses

200Campaign data found and returned successfully.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`data`	any	no	The campaign data object

400Invalid season parameter.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

404Campaign data not found.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

500Internal server error.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

post/api/h1/rebroadcast— Perform a campaign status or snapshot action

Request Body(required)

multipart/form-data

Property	Type	Required	Description
`action`	"get_campaign_status" \| "get_snapshots"	yes	The action to perform.
`season`	integer	no	Required if action is get_snapshots.

application/x-www-form-urlencoded

Property	Type	Required	Description
`action`	"get_campaign_status" \| "get_snapshots"	yes	The action to perform.
`season`	integer	no	Required if action is get_snapshots.

Responses

200Success

400Invalid request (content type, action, or arguments).

Property	Type	Required
`time`	number	yes
`error_code`	number	yes
`error_message`	string	yes

401Unauthorized. API key missing, malformed, or not found.

Property	Type	Required
`time`	number	yes
`error_code`	number	yes
`error_message`	string	yes

403Forbidden. API key found but disabled.

Property	Type	Required
`time`	number	yes
`error_code`	number	yes
`error_message`	string	yes

404Not found.

Property	Type	Required
`time`	number	yes
`error_code`	number	yes
`error_message`	string	yes

405Method not allowed.

Property	Type	Required
`time`	number	yes
`error_code`	number	yes
`error_message`	string	yes

get/api/h1/update— Trigger current campaign status and snapshot updates

**Internal-use-only.** This endpoint is used by a node (web) worker to continuously trigger status and season updates for the current campaign. It is not intended for external user consumption. Requires a valid `key` query parameter matching the server's `UPDATE_KEY` environment variable.

Parameters

Name	In	Type	Required	Description
key	query	string	yes	Internal API key for authorization.

Responses

200Update successful. Returns the updated status and season data.

Property Type Required Description

time number yes

code number yes

message string yes

data

object

yes

Property Type Required Description

updated

object

yes

Property	Type	Required	Description
`status`	any	no	The updated status data.
`season`	any	no	The updated season data.

400Bad request. Missing key parameter.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

401Unauthorized. The provided key is missing or invalid.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

405Method Not Allowed. Only GET is supported.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

500Internal server error.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

get/api/h1/live— Get current campaign state for live polling

Lightweight endpoint returning the current campaign data and computed map state. Designed for client-side polling via `useLiveData` hook at 10-second intervals.

Responses

200Current campaign state with computed map ownership.

Property	Type	Required	Description
`data`	any	no	Full campaign object
`mapState`	array	yes	Sector ownership array

500Database error fetching campaign data.

postdelete/api/notifications/subscribe

postSubscribe to push notifications

Registers a Web Push subscription. The server will send push notifications for campaign events (started, won, lost) to the provided endpoint.

Request Body(required)

application/json

Property Type Required Description

endpoint string yes The push subscription endpoint URL.

keys

object

yes

Property	Type	Required	Description
`p256dh`	string	yes	Base64-encoded P-256 ECDH public key.
`auth`	string	yes	Base64-encoded authentication secret.

Responses

201Subscription created or updated.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`data`	any	no	Response data

400Invalid JSON or missing required fields.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

500Internal server error.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

deleteUnsubscribe from push notifications

Removes a Web Push subscription by endpoint URL. Silently succeeds if the subscription does not exist.

Request Body(required)

application/json

Property	Type	Required	Description
`endpoint`	string	yes	The push subscription endpoint URL to remove.

Responses

200Subscription removed.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`data`	any	no	Response data

400Invalid JSON or missing endpoint.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null

500Internal server error.

Property	Type	Required	Description
`time`	number	yes	Time taken to process the request (ms)
`code`	number	yes	HTTP status code
`message`	string	yes	Human-readable status message
`error`	any	no	Error details or null