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 the /api/v1/h1/* reads and /api/h1/campaign. 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

The versioned /api/v1/h1/* endpoints and /api/h1/rebroadcast require a user API key via Authorization: Bearer <key>. Keys are created and managed from the user dashboard. /api/h1/update is internal (worker-only, Bearer token must match UPDATE_KEY). /api/h1/live is the dashboard's own feed — internal, not part of the public contract. /api/h1/campaign is public but deprecated.

Versioning & API surface

Human-readable endpoints live under a versioned path — /api/v1/h1/{status,stats,season,map}. Within /v1 the contract is stable: field names and semantics never change, and additive changes (new fields, new optional query filters) are non-breaking. A breaking shape change introduces /v2 while /v1 stays operational. The version lives in the path — there is no header-based version negotiation. The endpoint reference below documents the public surface only — internal plumbing is noted here but intentionally left out of the spec.

/api/v1/h1/*: Human-readable REST projection. Versioned, key-gated (user API key).
/api/h1/rebroadcast: Drop-in replacement for the official HD1 API (raw wire format). Deliberately unversioned and stable — it mirrors a frozen external contract, so it sits a level above /v1 and never moves under it. Key-gated.
/api/h1/live · /api/h1/update: Internal— the dashboard's rich live feed and the worker's update trigger (UPDATE_KEY-gated). Not part of the public contract and excluded from the spec below; they can change without notice.
/api/h1/campaign: Deprecated — superseded by /api/v1/h1/status + /api/v1/h1/stats.

Endpoints

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

Deprecated

**Deprecated** — superseded by `GET /api/v1/h1/status` (campaign progress) and `GET /api/v1/h1/stats` (statistics). 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

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— Drop-in replacement for the official HD1 API (raw wire format)

Reconstructs the official Helldivers 1 API wire format from normalized data, so existing HD1-API consumers can repoint here. Key-gated. Rate-limited per API key (`rebroadcast` group); responses carry `RateLimit-*` headers.

Request Body(required)

multipart/form-data

Property	Type	Required	Description
`action`	"get_campaign_status" \| "get_snapshots" \| "get_available_entitlements" \| "get_leaderboards" \| "get_usernames"	yes	The HD1-API action to perform. `get_campaign_status` and `get_snapshots` are implemented; `get_available_entitlements`, `get_leaderboards`, and `get_usernames` are recognised but not implemented (return 501) — Demand-Driven Compatibility, implemented on first real consumer.
`season`	integer	no	Required if action is get_snapshots.

application/x-www-form-urlencoded

Property	Type	Required	Description
`action`	"get_campaign_status" \| "get_snapshots" \| "get_available_entitlements" \| "get_leaderboards" \| "get_usernames"	yes	The HD1-API action to perform. `get_campaign_status` and `get_snapshots` are implemented; `get_available_entitlements`, `get_leaderboards`, and `get_usernames` are recognised but not implemented (return 501) — Demand-Driven Compatibility, implemented on first real consumer.
`season`	integer	no	Required if action is get_snapshots.

Responses

200Success

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

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. API key missing, malformed, or 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

403Forbidden. API key found but disabled.

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

404Not 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

405Method not allowed.

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

429Rate limit exceeded (`rebroadcast` group). See `RateLimit-*` and `Retry-After` headers.

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

501Action recognised but not implemented (`get_available_entitlements`, `get_leaderboards`, `get_usernames`).

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/v1/h1/status— Campaign status — latest snapshot or paginated history

Key-gated. `mode=latest` (default) returns the current per-faction campaign progress; `mode=history` returns a cursor-paginated timeseries. Cache-Control is tiered (`latest`/`current-season`/`closed-season`); history reads also carry an `ETag` and honour `If-None-Match` (304). Rate-limited per IP (`public_read` for latest, `history_read` for history).

Parameters

Name	In	Type	Required	Description
season	query	string	no	Season number, or 'current' (the default).
enemy	query	string	no	Restrict the response to a single faction.
mode	query	string	no	latest (default) or history.
from	query	string	no	ISO datetime lower bound (history).
to	query	string	no	ISO datetime upper bound (history).
limit	query	integer	no	Page size, 1–500 (default 100).
cursor	query	string	no	Opaque keyset cursor returned as `page.nextCursor` of a prior page.
order	query	string	no	Bucket order (default `desc`).

Responses

200Campaign status. Carries RateLimit-* and tiered Cache-Control headers; history also carries an ETag.

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

object

yes

Property Type Required Description

season number yes

mode "latest" | "history" yes

bucket number no

items array yes

page

object

yes

Property	Type	Required	Description
`limit`	number	yes
`nextCursor`	string	yes	Cursor for the next page, or null.

304Not Modified (history reads, when If-None-Match matches the ETag).

400Invalid query parameter or cursor.

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. API key missing, malformed, disabled, or 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

404Season 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

429Rate limit exceeded. Inspect the `RateLimit-Limit/Remaining/Reset` and `Retry-After` headers.

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/v1/h1/stats— Statistics timeseries for a season (cursor-paginated)

Key-gated. Per-bucket kill/death/mission/player statistics over `h1_statistic`. Tiered Cache-Control + ETag (304 via `If-None-Match`). Rate-limited per IP (`history_read`).

Parameters

Name	In	Type	Required	Description
season	query	string	no	Season number, or 'current' (the default).
enemy	query	string	no	Restrict the response to a single faction.
from	query	string	no	ISO datetime lower bound (history).
to	query	string	no	ISO datetime upper bound (history).
limit	query	integer	no	Page size, 1–500 (default 100).
cursor	query	string	no	Opaque keyset cursor returned as `page.nextCursor` of a prior page.
order	query	string	no	Bucket order (default `desc`).

Responses

200Statistics page. Carries RateLimit-*, Cache-Control, and ETag headers.

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

object

yes

Property Type Required Description

season number yes

bucketSize number yes Bucket width (seconds).

items array yes

page

object

yes

Property	Type	Required	Description
`limit`	number	yes
`nextCursor`	string	yes	Cursor for the next page, or null.

304Not Modified (when If-None-Match matches the ETag).

400Invalid query parameter or cursor.

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. API key missing, malformed, disabled, or 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

404Season 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

429Rate limit exceeded. Inspect the `RateLimit-Limit/Remaining/Reset` and `Retry-After` headers.

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/v1/h1/season— Season metadata (introduction order, points_max, duration)

Key-gated. Returns an array of season-metadata objects; pass the repeatable `season` param for several seasons (defaults to `current`). Cache-Control is `current-season` when the live season is included, else `closed-season`. Rate-limited per IP (`public_read`).

Parameters

Name	In	Type	Required	Description
season	query	string	no	Repeatable: pass multiple `season=` for several seasons. Each is a number or 'current' (default).

Responses

200Array of season metadata. Carries RateLimit-* and Cache-Control headers.

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`	array	yes

400Invalid query parameter or cursor.

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. API key missing, malformed, disabled, or 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

404Season 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

429Rate limit exceeded. Inspect the `RateLimit-Limit/Remaining/Reset` and `Retry-After` headers.

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/v1/h1/map— Render-ready galaxy map (per-faction fronts)

Key-gated. Returns the computed galaxy ownership as per-faction fronts (`bugs`/`cyborgs`/`illuminate`/`superEarth`), each an id-sorted array of regions. `at=latest` only for now (historical reconstruction is deferred). Rate-limited per IP (`public_read`); `latest` Cache-Control.

Parameters

Name	In	Type	Required	Description
season	query	string	no	Season number, or 'current' (the default).
at	query	string	no	`latest` only for now (historical `at=<datetime>` not yet supported).
enemy	query	string	no	Restrict the response to a single faction.
events	query	string	no	Whether to overlay active events (default `active`).

Responses

200Galaxy map. Carries RateLimit-* and Cache-Control headers.

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

object

yes

Property Type Required Description

season number yes

bucket number yes

events "active" | "none" yes

fronts

object

yes

Per-faction fronts (filtered by `enemy`).

Property	Type	Required
`bugs`	array	no
`cyborgs`	array	no
`illuminate`	array	no
`superEarth`	array	no

activeEvents array yes

400Invalid query parameter or cursor.

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. API key missing, malformed, disabled, or 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

404Season 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

429Rate limit exceeded. Inspect the `RateLimit-Limit/Remaining/Reset` and `Retry-After` headers.

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