Developer Reference

Telemetry & API Docs

Integrate with the CyCity Quantum Web Standard telemetry network. Monitor node status, validate licenses, and download daemon binaries.

Authentication

All API endpoints require authentication via Bearer token or License Key headers, depending on the endpoint context.

Authorization: Bearer <JWT_SOVEREIGN_TOKEN>

X-CQWS-License: <CQWS-XXXX-XXXX-XXXX>

POST

/api/entropy/chunk

Pulls true physical photon vacuum fluctuation entropy chunks generated directly by Quantum Dice DISC™ PCIe hardware cards.

Request Body (JSON)

{
  "machine_id": "prod-gateway-node-01",
  "bytes": 1024
}

Response (200 OK)

{
  "success": true,
  "bytes_served": 1024,
  "shannon_entropy": 7.999984,
  "data_base64": "vP38Q293c1...quantum_bytes...==",
  "timestamp": "2026-09-26T16:00:00Z"
}

WSS

/api/entropy/stream

Persistent binary WebSocket stream for line-rate continuous entropy injection into Linux /dev/random.

wss://cycity.cloud/api/entropy/stream?license_key=CQWS-XXXX-XXXX&chunk_size=4096

POST

/api/license/ping

Called by the `cqws_daemon.ko` kernel module every 5 minutes to report telemetry and validate license standing.

Request Body (JSON)

{
  "licenseKey": "CQWS-XXXX-XXXX-XXXX",
  "status": "active",
  "version": "4.2.0",
  "hostname": "node-us-east-1",
  "os": "Ubuntu 24.04 LTS"
}

Response (200 OK)

{
  "valid": true,
  "action": "continue",
  "nextPing": 300
}

GET

/api/download/installer

Downloads the zero-knowledge encrypted `cqws_installer.sh` payload. Requires a valid license key.

Query Parameters

`license_key` (string, required): The enterprise license key.

Response (200 OK - application/octet-stream)

Binary stream of the installer payload.

GET

/api/admin/telemetry

Retrieves aggregated telemetry for the admin dashboard. Requires Admin JWT Bearer token.

Response (200 OK)

{
  "totalNodes": 142,
  "activeNodes": 140,
  "packetsDropped": 1045239,
  "shannonEntropy": 7.999982,
  "alerts": []
}