API DOCUMENTATION

PUBLIC REST API FOR CRYOARCHIVE DATA

All endpoints are read-only and publicly accessible. Data is updated every 5 minutes by the Python poller. No authentication required.

BASE URL

https://breacher.net

All endpoints return JSON. Responses include a source field indicating the data origin. Cloudflare caching respects the Cache-Control headers set by each endpoint.

QUICK REFERENCE

METHOD	ENDPOINT	DESCRIPTION
GET	/api/health	Lightweight health check for K8s probes and uptime monitoring.
GET	/api/state/latest	Returns the most recent cryoarchive state snapshot — kill count, ship date, sector states, and memory flags.
GET	/api/state/history	Returns historical state snapshots with kill count, sectors, and memory flags over time.
GET	/api/stabilization/latest	Returns the latest camera stabilization snapshot — current stabilization levels and next stabilization time.
GET	/api/stabilization/history	Returns historical stabilization snapshots.
GET	/api/steam	Returns the current live Steam player count for Marathon.
GET	/api/steam/history	Returns historical Steam player count snapshots for Marathon.
GET	/api/builds/latest	Returns the most recent build/deployment event detected on cryoarchive.
GET	/api/builds	Returns a list of build/deployment change events in reverse chronological order.
GET	/api/index-entries	Returns all cryoarchive index entries with stats summary.

ENDPOINT REFERENCE

GET/api/health

Lightweight health check for K8s probes and uptime monitoring. Returns a simple status indicator with HTTP 200 (ok) or 503 (degraded).

RESPONSE FIELDS

Field	Type	Description
`status`	"ok" \| "degraded"	Service health — ok when DB is connected or unconfigured, degraded when DB is configured but unreachable

EXAMPLE RESPONSE

{
  "status": "ok"
}

GET/api/state/latestCACHE: 60s + 30s stale-while-revalidate

Returns the most recent cryoarchive state snapshot — kill count, ship date, sector states, and memory flags. Updated every 5 minutes by the poller.

RESPONSE FIELDS

Field	Type	Description
`data.capturedAt`	string (ISO 8601)	When this snapshot was captured
`data.killCount`	number	Current kill counter value
`data.shipDate`	string	Displayed ship date
`data.nextUpdate`	string	Next scheduled update time
`data.sectors`	object	Sector names → status mapping
`data.memoryFlags`	object	Memory flag states
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "capturedAt": "2026-03-17T12:00:00.000Z",
    "killCount": 476291,
    "shipDate": "JUL 23 2026",
    "nextUpdate": "...",
    "sectors": { "perimeter": "active", ... },
    "memoryFlags": { ... }
  },
  "source": "database"
}

GET/api/state/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical state snapshots with kill count, sectors, and memory flags over time. Use for charts and trend analysis.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	100	Max rows to return (max 1000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of state snapshot rows
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "kill_count": 476291,
      "ship_date": "JUL 23 2026",
      "build_version": "...",
      "sectors": { ... },
      "memory_flags": { ... }
    }
  ],
  "count": 100,
  "source": "database"
}

GET/api/stabilization/latestCACHE: 60s + 30s stale-while-revalidate

Returns the latest camera stabilization snapshot — current stabilization levels and next stabilization time.

RESPONSE FIELDS

Field	Type	Description
`data.capturedAt`	string (ISO 8601)	When this snapshot was captured
`data.cameras`	object	Camera name → stabilization object mapping
`data.nextStabilization`	string	Next stabilization event time
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "capturedAt": "2026-03-17T12:00:00.000Z",
    "cameras": {
      "camera_01": { "level": 87.5, "status": "stable" }
    },
    "nextStabilization": "2026-03-17T13:00:00Z"
  },
  "source": "database"
}

GET/api/stabilization/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical stabilization snapshots. Use for charting camera stabilization levels over time.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	100	Max rows to return (max 1000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of stabilization snapshot rows
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "cameras": { ... },
      "next_stabilization": "2026-03-17T13:00:00Z"
    }
  ],
  "count": 100,
  "source": "database"
}

GET/api/steamCACHE: 60s + 30s stale-while-revalidate

Returns the current live Steam player count for Marathon. Proxies the public ISteamUserStats endpoint — no API key required.

RESPONSE FIELDS

Field	Type	Description
`playerCount`	number	Current concurrent players on Steam
`appId`	number	Steam Application ID (3065800)
`timestamp`	string (ISO 8601)	Server time when fetched

EXAMPLE RESPONSE

{
  "playerCount": 1247,
  "appId": 3065800,
  "timestamp": "2026-03-17T12:00:00.000Z"
}

GET/api/steam/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical Steam player count snapshots for Marathon. Used by the player count chart for trend analysis.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	500	Max rows to return (max 2000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of { captured_at, player_count } objects
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "player_count": 1247
    }
  ],
  "count": 500,
  "source": "database"
}

GET/api/builds/latestCACHE: 60s + 30s stale-while-revalidate

Returns the most recent build/deployment event detected on cryoarchive.systems.

RESPONSE FIELDS

Field	Type	Description
`data.id`	number	Build event ID
`data.detected_at`	string (ISO 8601)	When the build was detected
`data.build_hash`	string	Build hash identifier
`data.build_version`	string	Build version string
`data.summary`	string	Human-readable summary of changes
`data.details`	object	Detailed change information
`data.headers`	object	HTTP headers from the build
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "id": 42,
    "detected_at": "2026-03-17T10:30:00Z",
    "build_hash": "abc123...",
    "build_version": "1.2.3",
    "summary": "New build deployed",
    "details": { ... },
    "headers": { ... }
  },
  "source": "database"
}

GET/api/builds

Returns a list of build/deployment change events in reverse chronological order.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	50	Max rows to return (max 200)

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of build event objects
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "id": 42,
      "detected_at": "2026-03-17T10:30:00Z",
      "build_hash": "abc123...",
      "build_version": "1.2.3",
      "summary": "New build deployed",
      "details": { ... },
      "headers": { ... }
    }
  ],
  "count": 50,
  "source": "database"
}

GET/api/index-entriesCACHE: 300s + 120s stale-while-revalidate

Returns all cryoarchive index entries with stats summary. Supports filtering by lock status and content type. Currently tracks 1,200+ entries.

QUERY PARAMETERS

Name	Type	Default	Description
`status`	"locked" \| "unlocked" \| "all"	"all"	Filter by lock status
`type`	"IMAGE" \| "TEXT" \| "VIDEO" \| "AUDIO"	—	Filter by content type

RESPONSE FIELDS

Field	Type	Description
`stats.total`	number	Total entries in database
`stats.unlocked`	number	Number of unlocked entries
`stats.locked`	number	Number of locked entries
`stats.types`	object	Count per type — IMAGE, TEXT, VIDEO, AUDIO, DOCUMENT, MEDIA
`entries`	array	Array of index entry objects
`fetchedAt`	string (ISO 8601)	When the query was executed
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "stats": {
    "total": 1247,
    "unlocked": 312,
    "locked": 935,
    "types": {
      "IMAGE": 856,
      "TEXT": 203,
      "VIDEO": 47,
      "AUDIO": 89,
      "DOCUMENT": 12,
      "MEDIA": 40
    }
  },
  "entries": [
    {
      "entry_id": "IDX-0001",
      "entry_type": "IMAGE",
      "status": "unlocked",
      "first_seen": "2026-01-15T...",
      "last_updated": "2026-03-17T...",
      "content_data": { ... }
    }
  ],
  "fetchedAt": "2026-03-17T12:00:00.000Z",
  "source": "database"
}

ERROR RESPONSES

All endpoints return consistent error shapes:

400

Invalid query parameter

{ "error": "Invalid limit: \\"abc\\" — must be a positive integer" }

500

Database query failed

{ "error": "Database query failed", "data": [], "source": "error" }

503

No data available (poller hasn't run)

{ "error": "No state data available yet — poller may not have run", "data": null, "source": "empty" }

RATE LIMITING & CACHING

A sliding-window rate limiter is applied per IP, per endpoint. Cloudflare also provides edge-level throttling. Data updates every 5 minutes — polling faster won't get fresher data.

Endpoint	Limit	Window
`/api/*/history`	20 req	60s
`/api/index-entries`	20 req	60s
`/api/status`	10 req	60s
`All others`	60 req	60s

▸Responses include Cache-Control headers — respect them
▸For bulk historical data, use the since param instead of fetching everything
▸If you're building a tool that polls regularly, 5-minute intervals are ideal

CONTRIBUTE →SOURCE CODE →

API DOCUMENTATION

PUBLIC REST API FOR CRYOARCHIVE DATA

All endpoints are read-only and publicly accessible. Data is updated every 5 minutes by the Python poller. No authentication required.

BASE URL

https://breacher.net

All endpoints return JSON. Responses include a source field indicating the data origin. Cloudflare caching respects the Cache-Control headers set by each endpoint.

QUICK REFERENCE

METHOD	ENDPOINT	DESCRIPTION
GET	/api/health	Lightweight health check for K8s probes and uptime monitoring.
GET	/api/state/latest	Returns the most recent cryoarchive state snapshot — kill count, ship date, sector states, and memory flags.
GET	/api/state/history	Returns historical state snapshots with kill count, sectors, and memory flags over time.
GET	/api/stabilization/latest	Returns the latest camera stabilization snapshot — current stabilization levels and next stabilization time.
GET	/api/stabilization/history	Returns historical stabilization snapshots.
GET	/api/steam	Returns the current live Steam player count for Marathon.
GET	/api/steam/history	Returns historical Steam player count snapshots for Marathon.
GET	/api/builds/latest	Returns the most recent build/deployment event detected on cryoarchive.
GET	/api/builds	Returns a list of build/deployment change events in reverse chronological order.
GET	/api/index-entries	Returns all cryoarchive index entries with stats summary.

ENDPOINT REFERENCE

GET/api/health

Lightweight health check for K8s probes and uptime monitoring. Returns a simple status indicator with HTTP 200 (ok) or 503 (degraded).

RESPONSE FIELDS

Field	Type	Description
`status`	"ok" \| "degraded"	Service health — ok when DB is connected or unconfigured, degraded when DB is configured but unreachable

EXAMPLE RESPONSE

{
  "status": "ok"
}

GET/api/state/latestCACHE: 60s + 30s stale-while-revalidate

Returns the most recent cryoarchive state snapshot — kill count, ship date, sector states, and memory flags. Updated every 5 minutes by the poller.

RESPONSE FIELDS

Field	Type	Description
`data.capturedAt`	string (ISO 8601)	When this snapshot was captured
`data.killCount`	number	Current kill counter value
`data.shipDate`	string	Displayed ship date
`data.nextUpdate`	string	Next scheduled update time
`data.sectors`	object	Sector names → status mapping
`data.memoryFlags`	object	Memory flag states
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "capturedAt": "2026-03-17T12:00:00.000Z",
    "killCount": 476291,
    "shipDate": "JUL 23 2026",
    "nextUpdate": "...",
    "sectors": { "perimeter": "active", ... },
    "memoryFlags": { ... }
  },
  "source": "database"
}

GET/api/state/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical state snapshots with kill count, sectors, and memory flags over time. Use for charts and trend analysis.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	100	Max rows to return (max 1000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of state snapshot rows
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "kill_count": 476291,
      "ship_date": "JUL 23 2026",
      "build_version": "...",
      "sectors": { ... },
      "memory_flags": { ... }
    }
  ],
  "count": 100,
  "source": "database"
}

GET/api/stabilization/latestCACHE: 60s + 30s stale-while-revalidate

Returns the latest camera stabilization snapshot — current stabilization levels and next stabilization time.

RESPONSE FIELDS

Field	Type	Description
`data.capturedAt`	string (ISO 8601)	When this snapshot was captured
`data.cameras`	object	Camera name → stabilization object mapping
`data.nextStabilization`	string	Next stabilization event time
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "capturedAt": "2026-03-17T12:00:00.000Z",
    "cameras": {
      "camera_01": { "level": 87.5, "status": "stable" }
    },
    "nextStabilization": "2026-03-17T13:00:00Z"
  },
  "source": "database"
}

GET/api/stabilization/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical stabilization snapshots. Use for charting camera stabilization levels over time.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	100	Max rows to return (max 1000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of stabilization snapshot rows
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "cameras": { ... },
      "next_stabilization": "2026-03-17T13:00:00Z"
    }
  ],
  "count": 100,
  "source": "database"
}

GET/api/steamCACHE: 60s + 30s stale-while-revalidate

Returns the current live Steam player count for Marathon. Proxies the public ISteamUserStats endpoint — no API key required.

RESPONSE FIELDS

Field	Type	Description
`playerCount`	number	Current concurrent players on Steam
`appId`	number	Steam Application ID (3065800)
`timestamp`	string (ISO 8601)	Server time when fetched

EXAMPLE RESPONSE

{
  "playerCount": 1247,
  "appId": 3065800,
  "timestamp": "2026-03-17T12:00:00.000Z"
}

GET/api/steam/historyCACHE: 120s + 60s stale-while-revalidate

Returns historical Steam player count snapshots for Marathon. Used by the player count chart for trend analysis.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	500	Max rows to return (max 2000)
`since`	ISO 8601 timestamp	—	Only return snapshots after this time

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of { captured_at, player_count } objects
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "captured_at": "2026-03-17T12:00:00Z",
      "player_count": 1247
    }
  ],
  "count": 500,
  "source": "database"
}

GET/api/builds/latestCACHE: 60s + 30s stale-while-revalidate

Returns the most recent build/deployment event detected on cryoarchive.systems.

RESPONSE FIELDS

Field	Type	Description
`data.id`	number	Build event ID
`data.detected_at`	string (ISO 8601)	When the build was detected
`data.build_hash`	string	Build hash identifier
`data.build_version`	string	Build version string
`data.summary`	string	Human-readable summary of changes
`data.details`	object	Detailed change information
`data.headers`	object	HTTP headers from the build
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": {
    "id": 42,
    "detected_at": "2026-03-17T10:30:00Z",
    "build_hash": "abc123...",
    "build_version": "1.2.3",
    "summary": "New build deployed",
    "details": { ... },
    "headers": { ... }
  },
  "source": "database"
}

GET/api/builds

Returns a list of build/deployment change events in reverse chronological order.

QUERY PARAMETERS

Name	Type	Default	Description
`limit`	integer	50	Max rows to return (max 200)

RESPONSE FIELDS

Field	Type	Description
`data`	array	Array of build event objects
`count`	number	Number of rows returned
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "data": [
    {
      "id": 42,
      "detected_at": "2026-03-17T10:30:00Z",
      "build_hash": "abc123...",
      "build_version": "1.2.3",
      "summary": "New build deployed",
      "details": { ... },
      "headers": { ... }
    }
  ],
  "count": 50,
  "source": "database"
}

GET/api/index-entriesCACHE: 300s + 120s stale-while-revalidate

Returns all cryoarchive index entries with stats summary. Supports filtering by lock status and content type. Currently tracks 1,200+ entries.

QUERY PARAMETERS

Name	Type	Default	Description
`status`	"locked" \| "unlocked" \| "all"	"all"	Filter by lock status
`type`	"IMAGE" \| "TEXT" \| "VIDEO" \| "AUDIO"	—	Filter by content type

RESPONSE FIELDS

Field	Type	Description
`stats.total`	number	Total entries in database
`stats.unlocked`	number	Number of unlocked entries
`stats.locked`	number	Number of locked entries
`stats.types`	object	Count per type — IMAGE, TEXT, VIDEO, AUDIO, DOCUMENT, MEDIA
`entries`	array	Array of index entry objects
`fetchedAt`	string (ISO 8601)	When the query was executed
`source`	"database"	Data source

EXAMPLE RESPONSE

{
  "stats": {
    "total": 1247,
    "unlocked": 312,
    "locked": 935,
    "types": {
      "IMAGE": 856,
      "TEXT": 203,
      "VIDEO": 47,
      "AUDIO": 89,
      "DOCUMENT": 12,
      "MEDIA": 40
    }
  },
  "entries": [
    {
      "entry_id": "IDX-0001",
      "entry_type": "IMAGE",
      "status": "unlocked",
      "first_seen": "2026-01-15T...",
      "last_updated": "2026-03-17T...",
      "content_data": { ... }
    }
  ],
  "fetchedAt": "2026-03-17T12:00:00.000Z",
  "source": "database"
}

ERROR RESPONSES

All endpoints return consistent error shapes:

400

Invalid query parameter

{ "error": "Invalid limit: \\"abc\\" — must be a positive integer" }

500

Database query failed

{ "error": "Database query failed", "data": [], "source": "error" }

503

No data available (poller hasn't run)

{ "error": "No state data available yet — poller may not have run", "data": null, "source": "empty" }

RATE LIMITING & CACHING

A sliding-window rate limiter is applied per IP, per endpoint. Cloudflare also provides edge-level throttling. Data updates every 5 minutes — polling faster won't get fresher data.

Endpoint	Limit	Window
`/api/*/history`	20 req	60s
`/api/index-entries`	20 req	60s
`/api/status`	10 req	60s
`All others`	60 req	60s

▸Responses include Cache-Control headers — respect them
▸For bulk historical data, use the since param instead of fetching everything
▸If you're building a tool that polls regularly, 5-minute intervals are ideal

CONTRIBUTE →SOURCE CODE →