basePath: /api/v1 definitions: github_com_MeshCore-Beacon_beacon-server_internal_api.Account: properties: active: type: boolean created_at: type: string deactivated_at: type: string id: type: string name: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList: properties: items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account' type: array type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AdminAuthConfig: properties: configured: type: boolean type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AdminCORSConfig: properties: allow_credentials: type: boolean allowed_headers: items: type: string type: array allowed_methods: items: type: string type: array allowed_origins: items: type: string type: array max_age: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig: properties: auth: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminAuthConfig' cors: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminCORSConfig' ingest: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminIngestConfig' type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AdminIngestConfig: properties: broker_count: description: |- BrokerCount counts configured broker workers, not active MQTT connections or a configurable processing-worker pool. type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation: properties: heardAt: description: epoch ms type: integer hopCount: type: integer iata: type: string id: description: observation ID, use as cursor for pagination type: integer nodeName: type: string nodePublicKey: description: hex-encoded type: string packetHash: description: hex-encoded type: string payloadType: type: integer payloadTypeName: type: string rssi: type: integer snr: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Channel: properties: channelHash: description: hex-encoded single-byte hash type: string hashtag: description: 'tag name without # prefix; non-nil only for hashtag channels' type: string id: type: integer isHashtag: description: true if key was derived from a hashtag PSK type: boolean keyFingerprint: description: first 8 bytes of SHA256(key), hex-encoded type: string keyKnown: description: true if Beacon has a decryption key for this channel type: boolean lastSeen: description: epoch ms, time of most recent message type: integer messageCount: description: lifetime count; not reduced by retention type: integer name: description: display name from config or nil type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage: properties: channelHash: description: hex-encoded single-byte channel hash type: string content: description: decrypted message text type: string id: type: integer observationCount: description: number of packet_observations rows for this message's packet hash type: integer packetHash: description: hex-encoded packet hash for correlation with packet events type: string scope: description: matched scope on the first stored packet; null when none was recorded type: string scopeStatus: enum: - matched - unscoped - unknown - unavailable type: string senderName: description: display name from the decrypted payload type: string sentAt: description: epoch ms, from the sender's embedded timestamp type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelPage: properties: hasMore: type: boolean items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary' type: array nextCursor: type: integer nextPageCursor: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary: properties: channelHash: description: hex-encoded single-byte hash type: string id: type: integer isHashtag: description: true if key was derived from a hashtag PSK type: boolean keyKnown: description: true if Beacon has a decryption key for this channel type: boolean lastSeen: description: epoch ms, time of most recent message type: integer name: description: display name from config or nil type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry: properties: clockCheckedAt: description: epoch ms type: integer clockDriftSeconds: description: signed; +ve = device ahead of server type: integer iatas: description: IATAs this node has been heard in items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA' type: array nodeId: type: string nodeName: type: string nodeType: type: integer nodeTypeName: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest: properties: name: type: string required: - name type: object github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop: properties: fromIata: type: string fromNode: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode' description: last node in source IATA lastSeen: description: epoch ms type: integer toIata: type: string toNode: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode' description: first node in target IATA type: object github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute: properties: crossHop: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop' description: the boundary hop sourceSegment: description: route segment in source IATA items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop' type: array targetSegment: description: route segment in target IATA items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop' type: array totalHops: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.IATA: properties: displayName: type: string iata: type: string lat: type: number lon: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute: properties: firstSeen: description: epoch ms type: integer hopCount: type: integer hops: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop' type: array iata: type: string id: type: integer lastSeen: description: epoch ms type: integer observationCount: type: integer pathKey: description: stable identity within this IATA; use for route evidence links type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Node: properties: clockCheckedAt: type: integer clockDriftSeconds: description: |- Clock drift, repeaters/room servers only (nodeType 2/3); omitted entirely for other node types or when no qualifying advert has been measured yet. Device minus server time, in seconds, from the advert's self-reported timestamp: +ve = device ahead. clockCheckedAt is the server receive time of the advert this was measured from (same moment as lastAdvertAt). clockOutOfSync is |clockDriftSeconds| exceeding a configured threshold (default 5m) -- see internal/config.ResolvedConfig.ClockDriftThreshold. type: integer clockOutOfSync: type: boolean defaultScope: description: most recently matched transport scope name e.g. "#bc" type: string firstSeen: description: epoch ms type: integer iatas: description: IATAs where this node has been heard, with last heard timestamps items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA' type: array id: type: string isObserver: description: true if this node is also a known observer type: boolean knownNeighborCount: type: integer lastAdvertAt: description: epoch ms, nil if no advert received type: integer lastSeen: description: epoch ms type: integer lat: description: decimal degrees, from advert AppData type: number lng: description: decimal degrees, from advert AppData type: number locationSource: description: '"advert" or "manual"' type: string metadata: description: raw JSONB metadata minFirmwareVersion: description: derived from capability flags type: string name: type: string neighborIds: description: only populated when the list request opts in; see ?neighbors=true items: type: string type: array neighbors: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor' type: array nodeType: description: 1=companion, 2=repeater, 3=room_server, 4=sensor type: integer nodeTypeName: type: string observerId: description: UUID of the associated observer row, if any type: string possiblyForeign: description: |- PossiblyForeign compares a repeater's stored position with this server's configured IATA border union. Omitted when disabled, unknown, or not repeater. type: boolean publicKey: description: hex-encoded Ed25519 public key type: string radio: description: 'shorthand: "freqMhz,bwKhz,sf" e.g. "910.525,62.5,7"' type: string stale: description: |- Stale is true when the node hasn't been seen (last_seen) within the configured staleness window (default 24h; internal/config.ResolvedConfig.NodeStaleThreshold). Applies to every node type, unlike ClockDriftSeconds/ClockOutOfSync on Node, which are repeater/room-server only. type: boolean supportsMultibytePaths: description: firmware >= 1.14.0; detected via path hash size type: boolean supportsMultibyteTraces: description: firmware >= 1.11.0; detected via trace hash size type: boolean type: object github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA: properties: iata: type: string lastHeard: description: epoch ms type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor: properties: firstSeen: description: epoch ms type: integer iata: type: string id: type: string lastSeen: description: epoch ms type: integer lat: type: number lng: type: number name: type: string nodeType: type: integer nodeTypeName: type: string observationCount: type: integer publicKey: type: string snr: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.NodeSummary: properties: defaultScope: description: most recently matched transport scope name e.g. "#bc" type: string iatas: description: IATAs where this node has been heard, with last heard timestamps items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA' type: array id: type: string isObserver: description: true if this node is also a known observer type: boolean knownNeighborCount: type: integer lat: description: decimal degrees, from advert AppData type: number lng: description: decimal degrees, from advert AppData type: number name: type: string neighborIds: description: only populated when the list request opts in; see ?neighbors=true items: type: string type: array nodeType: description: 1=companion, 2=repeater, 3=room_server, 4=sensor type: integer nodeTypeName: type: string observerId: description: UUID of the associated observer row, if any type: string possiblyForeign: description: |- PossiblyForeign compares a repeater's stored position with this server's configured IATA border union. Omitted when disabled, unknown, or not repeater. type: boolean publicKey: description: hex-encoded Ed25519 public key type: string radio: description: 'shorthand: "freqMhz,bwKhz,sf" e.g. "910.525,62.5,7"' type: string stale: description: |- Stale is true when the node hasn't been seen (last_seen) within the configured staleness window (default 24h; internal/config.ResolvedConfig.NodeStaleThreshold). Applies to every node type, unlike ClockDriftSeconds/ClockOutOfSync on Node, which are repeater/room-server only. type: boolean type: object github_com_MeshCore-Beacon_beacon-server_internal_api.NodeTypeCount: properties: count: type: integer nodeType: type: integer nodeTypeName: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObservationPoint: properties: hour: description: epoch ms, start of the 1-hour bucket type: integer iata: type: string observationCount: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Observer: properties: batteryLevel: description: volts, nil if mains powered type: number brokers: description: broker names this observer has been seen on items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverBroker' type: array displayName: description: friendly name from /status messages type: string firmwareBuild: type: string firmwareVersion: type: string firstSeen: description: epoch ms type: integer hardwareModel: type: string iata: description: most recently heard IATA type: string id: type: string lastSeen: description: epoch ms type: integer lastStatusAt: description: epoch ms type: integer observationCount: description: legacy cumulative presence counter; includes non-packet events type: integer observerType: description: e.g. "meshcoretomqtt", "meshcoreha" type: string publicKey: description: hex-encoded public key type: string radio: description: 'friendly radio param string: freqMhz,BwKhz,SF e.g. "910.525,62.5,7"' type: string radioBwKhz: description: bandwidth in kHz type: number radioCr: description: coding rate denominator type: integer radioFreqMhz: description: MHz e.g. 910.525 type: number radioSf: description: LoRa spreading factor type: integer scopes: description: list of observer forwarded scopes matched to config items: type: string type: array softwareVersion: type: string status: description: '"online" or "offline" derived from last_status_at' type: string statusMetadata: description: raw /status JSON payload type: object uptimeSeconds: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivity: properties: generatedAt: description: response computation time, not proof of continuous coverage type: integer interval: type: string payloadTypes: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem' type: array points: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityPoint' type: array radio: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityRadio' range: type: string source: description: raw or hourly; missing records do not prove an outage type: string summary: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivitySummary' windowEnd: description: exclusive end, epoch ms; live requests include the current partial bucket type: integer windowStart: description: inclusive complete-bucket start, epoch ms type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityPoint: properties: airtimeMs: type: number observations: type: integer rssiAvg: type: number snrAvg: type: number snrMin: type: number t: description: bucket start, epoch ms type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityRadio: properties: bwKhz: type: number cr: type: integer freqMhz: type: number preambleSymbols: type: integer sf: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivitySummary: properties: lastCompleteHour: type: integer lastCompleteHourEnd: type: integer lastCompleteHourStart: type: integer latestRecordedAt: type: integer recordedPackets: description: stored observations within windowStart/windowEnd type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverBroker: properties: lastPacketAt: description: epoch ms, last packet received via this broker; 0 if none type: integer lastSeenAt: description: epoch ms, last time observer was seen on this broker type: integer name: description: broker name e.g. "mqtt1" type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverComparison: properties: both: type: integer observerA: type: string observerB: type: string onlyA: type: integer onlyB: type: integer since: description: inclusive, epoch milliseconds type: integer totalPackets: type: integer until: description: exclusive, epoch milliseconds type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverSummary: properties: displayName: description: friendly name from /status messages type: string iata: description: most recently heard IATA type: string id: type: string observerType: description: e.g. "meshcoretomqtt", "meshcoreha" type: string radio: description: 'friendly radio param string: freqMhz,BwKhz,SF e.g. "910.525,62.5,7"' type: string scopes: description: list of observer forwarded scopes matched to config items: type: string type: array status: description: '"online" or "offline" derived from last_status_at' type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetry: properties: interval: type: string points: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint' type: array range: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint: properties: airtimeRxSecs: type: number airtimeTxSecs: type: number batteryMv: type: integer noiseFloorDb: type: number queueLength: type: integer receiveErrors: type: integer t: description: epoch ms type: integer uptimeSeconds: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Packet: properties: channelHash: description: hex-encoded single byte; non-nil for group_text/group_data type: string decrypted: description: true if group text was successfully decrypted type: boolean firstHeardAt: description: epoch ms type: integer firstToLastMs: description: ms between first and last observation type: integer header: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketHeader' lastHeardAt: description: epoch ms type: integer observationCount: type: integer observations: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail' type: array originPubkey: description: hex-encoded; nil when not extractable from payload type: string packetHash: type: string parsedPayload: items: type: integer type: array rawPayload: description: hex-encoded payload bytes (excludes header and path) type: string resolvedRoute: description: 'trace packets only: resolved intended route' items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' type: array scope: description: matched transport scope name e.g. "#bc" type: string transportCodes: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes' type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketHeader: properties: payloadType: description: bits 2-5 type: integer payloadTypeName: description: advert, request, group_text, etc. type: string payloadVersion: description: bits 6-7 type: integer raw: description: hex-encoded single byte type: string routeType: description: bits 0-1 type: integer routeTypeName: description: FLOOD, DIRECT, TRANSPORT_FLOOD, TRANSPORT_DIRECT type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketLatestObserver: properties: displayName: type: string iata: type: string id: type: string pathBytes: description: hex-encoded accumulated path hashes type: string pathLength: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength' description: |- PathLength/PathBytes and captured endpoint resolutions are stored on the observation, so list/backfill reads need no per-hash resolution queries. Legacy observations have no endpoint snapshot. ResolvedPath remains a detail/opted-in WS feature. resolvedDestination: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' resolvedPath: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' type: array resolvedSource: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail: properties: heardAt: description: epoch ms type: integer iata: type: string id: type: integer observerId: type: string observerName: type: string pathBytes: description: hex-encoded accumulated path hashes type: string pathLength: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength' propagationTimeMs: description: ms since first observation; 0 for first type: integer radio: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketRadio' resolvedDestination: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' resolvedPath: description: per-observation resolved path hashes items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' type: array resolvedSource: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' description: |- ResolvedSource/ResolvedDestination are the packet's endpoints, when the payload type carries one. Prefer the snapshot captured at ingest; legacy observations without a snapshot use the current node registry. Endpoint matching itself is unchanged: an exact match for ADVERT's full pubkey, an ambiguous hash-prefix match (like intermediate hops) for TEXT_MESSAGE/PATH/ANON_REQ's 1-byte source/destination hashes. Nil when the payload type doesn't carry one at all (e.g. GRP_TXT/GRP_DATA/TRACE aren't node-to-node addressed) -- see BuildResolvedPath and ResolveExactNode for how each is built. rssi: type: integer snr: type: number sourceBroker: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary: properties: heardAt: description: epoch ms type: integer hopCount: type: integer iata: type: string id: description: observation ID, use as cursor for pagination type: integer packetHash: description: hex-encoded type: string payloadType: type: integer payloadTypeName: type: string rssi: type: integer snr: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength: properties: hashSize: description: per-hop hash size in bytes (1, 2, or 3) type: integer hopCount: description: number of path hashes present type: integer raw: description: hex-encoded single byte type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketRadio: properties: bandwidthKhz: type: number codingRate: type: integer freqMhz: type: number spreadFactor: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketSummary: properties: firstHeardAt: description: epoch ms type: integer lastHeardAt: description: epoch ms type: integer latestObserver: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketLatestObserver' observationCount: type: integer packetHash: description: hex-encoded type: string payloadType: type: integer payloadTypeName: type: string routeType: type: integer routeTypeName: type: string scope: description: matched transport scope name e.g. "#bc" type: string summary: description: advert name, or the ACK/TRACE/PING summary; omitted when unavailable type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes: properties: regionCode: type: integer subRegionCode: type: integer type: object ? github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_AdvertObservation : properties: hasMore: type: boolean items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation' type: array nextCursor: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_NodeSummary: properties: hasMore: type: boolean items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeSummary' type: array nextCursor: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_ObserverSummary: properties: hasMore: type: boolean items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverSummary' type: array nextCursor: type: integer type: object ? github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_PacketObservationSummary : properties: hasMore: type: boolean items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary' type: array nextCursor: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth: properties: bytes: type: integer receptions: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour: properties: empty: type: integer hour: type: integer maxEntries: description: longest path received that hour across the requested IATAs; 0 if only empty paths type: integer oneByte: type: integer receptions: type: integer threeByte: type: integer trace: type: integer twoByte: type: integer unclassified: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin: properties: entries: type: integer receptions: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats: properties: empty: type: integer hashWidths: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth' type: array hashed: type: integer hourly: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour' type: array pathLengths: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin' type: array receptions: type: integer since: type: integer trace: type: integer unclassified: type: integer until: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem: properties: count: type: integer payloadType: type: integer payloadTypeName: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset: properties: count: description: number of observers or nodes on this preset in this IATA type: integer iata: type: string preset: description: '"freqMhz,bwKhz,sf" e.g. "910.525,62.5,7"' type: string sourceType: description: '"observer" or "node"' type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop: properties: hash: description: hex-encoded path hash type: string snr: description: signal-to-noise ratio in dB, if available type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.Region: properties: centerLat: description: map center latitude type: number centerLng: description: map center longitude type: number description: type: string iatas: description: member IATA codes items: type: string type: array id: type: integer name: type: string slug: description: URL-safe identifier e.g. "western-canada" type: string zoomLevel: description: suggested map zoom level type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary: properties: id: type: integer name: type: string slug: description: URL-safe identifier e.g. "western-canada" type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop: properties: confidence: description: '"high", "ambiguous", or "none"' type: string nodes: description: empty for "none", one for "high", multiple for "ambiguous" items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode' type: array snr: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode: properties: id: type: string latitude: type: number longitude: type: number name: type: string publicKey: description: hex-encoded prefix used for resolution type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RouteEvidence: properties: generatedAt: type: integer hasMore: type: boolean hashSize: type: integer items: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteObservation' type: array matchAvailable: type: boolean matchType: type: string nextPageCursor: type: string pathBytes: type: string route: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute' windowEnd: type: integer windowStart: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop: properties: hashBytes: description: hex-encoded hash prefix type: string node: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode' description: populated when node details are available nodeId: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.RouteObservation: properties: heardAt: type: integer id: type: integer observerId: type: string observerName: type: string packetHash: type: string payloadType: type: integer payloadTypeName: type: string rssi: type: integer snr: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail: properties: iataCount: type: integer iatas: items: type: string type: array name: type: string nodeCount: type: integer observerCount: type: integer packetCount: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour: properties: hour: description: epoch ms, start of the UTC hour type: integer nodes: description: distinct nodes whose adverts were heard in the scope that hour type: integer observers: description: distinct observers that heard the scope's packets that hour type: integer packets: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats: properties: hourly: description: packetCount by hour, oldest first; hours with none omitted items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour' type: array name: description: normalized scope name e.g. "#bc" type: string nodeCount: description: distinct nodes with this as their default scope type: integer observerCount: description: distinct observers that forwarded packets in this scope type: integer packetCount: description: distinct packets matched to this scope type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin: properties: count: type: integer lower: type: number upper: type: number type: object github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour: properties: hour: type: integer receptions: type: integer rssiAverage: type: number rssiSamples: type: integer snrAverage: type: number snrSamples: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric: properties: average: type: number histogram: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin' type: array samples: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.SignalStats: properties: hourly: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour' type: array receptions: type: integer rssi: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric' since: type: integer snr: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric' until: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.StatsOverview: properties: activeIatas: type: integer activeObservers: type: integer since: description: epoch ms, start of the window type: integer totalObservations: type: integer totalPackets: description: distinct per hour (see StatsSeriesValues) type: integer until: description: epoch ms, exclusive end of the window type: integer windowHours: description: always 24 for now type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeries: properties: completeHours: description: hours contributing to summary type: integer earliestComplete: description: first complete hour held, epoch ms; null if none type: integer hours: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesHour' type: array revision: description: changes whenever rolled hours, their status or coverage change type: integer since: description: effective start, epoch ms on a UTC hour type: integer summary: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues' until: description: effective exclusive end, epoch ms on a UTC hour type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesHour: properties: hour: description: epoch ms, start of the hour type: integer status: description: 'partial: raw rows deleted before it was rolled' enum: - complete - partial - missing type: string values: allOf: - $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues' description: null unless complete type: object github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues: properties: activeIatas: description: distinct across the hour or window type: integer activeObservers: description: distinct across the hour or window type: integer activeScopes: description: distinct across the hour or window type: integer maxPathEntries: type: integer observations: type: integer rssiSamples: type: integer rssiSum: description: average = rssiSum / rssiSamples type: number scopedPackets: type: integer snrSamples: type: integer snrSum: description: average = snrSum / snrSamples type: number uniquePackets: type: integer type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser: properties: advertCount: type: integer directAdvertCount: type: integer floodAdvertCount: description: |- FloodAdvertCount/DirectAdvertCount split AdvertCount by how the advert was routed: flood = route type 0 (transport_flood) or 1 (flood), broadcast with no known path; direct = route type 2 (direct) or 3 (transport_direct), routed along a known path. FloodAdvertCount + DirectAdvertCount == AdvertCount. type: integer iata: type: string lastHeard: description: epoch ms type: integer nodeId: description: null once the node row has been deleted type: string nodeName: type: string nodeType: type: integer nodeTypeName: type: string publicKey: description: hex type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode: properties: iata: type: string lastHeard: description: epoch ms type: integer nodeId: description: null once the node row has been deleted type: string nodeName: type: string nodeType: type: integer nodeTypeName: type: string observationCount: type: integer publicKey: description: hex type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver: properties: displayName: type: string iata: type: string observationCount: type: integer observerId: type: string observerType: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker: properties: lastSent: description: epoch ms type: integer messageCount: type: integer senderName: type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TraceDetail: properties: packets: description: all packets observed for this trace items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket' type: array traceTag: description: hex-encoded 4-byte tag type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket: properties: firstHeardAt: description: epoch ms type: integer lastHeardAt: description: epoch ms type: integer packetHash: description: hex-encoded packet hash type: string rawPath: description: hops as received in the packet items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop' type: array resolvedRoute: description: hops resolved to known nodes items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop' type: array routeType: description: numeric route type type: integer routeTypeName: description: human-readable route type type: string scope: description: transport scope name, if known type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary: properties: firstHeardAt: description: epoch ms type: integer iataCount: description: number of distinct IATAs where heard type: integer lastHeardAt: description: epoch ms type: integer packetCount: description: number of packets with this trace tag type: integer pathHashes: description: hops from the most complete observation items: type: string type: array snrValues: description: SNR per hop from the most complete observation items: type: number type: array traceTag: description: hex-encoded 4-byte tag type: string traceType: description: TRACE or PING type: string type: object github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest: properties: allowed_origins: items: type: string type: array required: - allowed_origins type: object github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest: properties: cors: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest' required: - cors type: object github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse: properties: config: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig' persisted: type: boolean requires_restart: type: boolean type: object internal_api_handlers.APIError: properties: code: description: e.g. "not_found", "bad_request" type: string message: description: e.g. "channel not found" type: string type: object internal_api_handlers.BrokerStatus: properties: connected: type: boolean name: type: string type: object host: localhost:8080 info: contact: name: MeshCore Beacon url: https://github.com/MeshCore-Beacon/beacon-server description: |- MeshCore network observation backend. Ingests LoRa packets from MQTT brokers, stores in PostgreSQL, and streams live events via WebSocket. REST requests share a configurable per-client rate limit (default 300/minute and a 300-request one-second burst cap). Exceeded limits return HTTP 429 with error.code=rate_limited and a Retry-After header in seconds. CORS preflights and WebSocket upgrades do not consume this API budget. WebSocket upgrade attempts at /ws have a configurable per-client limit (default 10/minute, including failed handshakes). Rate exhaustion returns HTTP 429 with Retry-After before upgrade. An accepted socket exceeding the concurrent cap closes with code 1013 before hello; established connections remain open. license: name: AGPL-3-or-later termsOfService: https://github.com/MeshCore-Beacon/beacon-server title: MeshCore Beacon API version: 2.0.0 paths: /admin/accounts: get: description: Includes active and inactive accounts, newest first. These records are not login users. produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList' "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "500": description: Internal Server Error schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: List operator accounts tags: - Admin post: consumes: - application/json description: Trims the name; names are case-sensitive and unique among active accounts. No credential or login is created. parameters: - description: Account name (1-128 Unicode characters, no control characters); body at most 4 KiB in: body name: account required: true schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest' produces: - application/json responses: "201": description: Created schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account' "400": description: Bad Request schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "409": description: Conflict schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "413": description: Request Entity Too Large schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "415": description: Unsupported Media Type schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "500": description: Internal Server Error schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Create an operator account tags: - Admin /admin/accounts/{id}: delete: description: Soft deactivation preserves the record. Its name may be reused by a new account. parameters: - description: Account UUID format: uuid in: path name: id required: true type: string produces: - application/json responses: "204": description: Deactivated "400": description: Bad Request schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "404": description: Not Found schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "409": description: Conflict schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "500": description: Internal Server Error schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Deactivate an operator account tags: - Admin get: description: Returns active or inactive account records. parameters: - description: Account UUID format: uuid in: path name: id required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account' "400": description: Bad Request schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "404": description: Not Found schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "500": description: Internal Server Error schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Get an operator account tags: - Admin /admin/backup: get: description: Opt-in operator export. Returns only a completed bundle; one export/transfer at a time. Contains secrets. Login sessions, external deployment files and import are outside this endpoint. produces: - application/gzip responses: "200": description: OK headers: Content-Disposition: description: attachment; filename=beacon-backup.tar.gz type: string schema: type: file "400": description: Bad Request schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "409": description: Conflict schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "500": description: Internal Server Error schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "504": description: Gateway Timeout schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "507": description: Insufficient Storage schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Download a private database and saved-config backup tags: - Admin /admin/config: get: description: Returns current CORS options, auth configuration status and configured broker count. Credential fields and other configuration are excluded. Runtime origin updates are lost on restart. produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig' "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Inspect selected running configuration tags: - Admin put: consumes: - application/json description: Replaces only cors.allowed_origins immediately. Updates are serialized; concurrent valid updates are applied one at a time. Already-running requests may finish with the previous policy. Nothing is persisted; restart reloads saved configuration. parameters: - description: 1-32 ASCII HTTP(S) origins, at most 512 bytes each; one hostname wildcard is supported, or a sole *. Empty/null lists and unsupported fields are rejected. Body at most 16 KiB. in: body name: config required: true schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest' produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse' "400": description: Bad Request schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "401": description: Unauthorized schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "413": description: Request Entity Too Large schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "415": description: Unsupported Media Type schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object "503": description: Service Unavailable schema: additionalProperties: $ref: '#/definitions/internal_api_handlers.APIError' type: object security: - AdminKey: [] summary: Update runtime CORS origins tags: - Admin /brokers: get: produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/internal_api_handlers.BrokerStatus' type: array summary: List all MQTT brokers and their connection status tags: - Brokers /channels: get: parameters: - description: Single-byte channel hash (hex) in: query name: hash type: string - description: 'Filter by IATA code: channels MeshMapper lists there, config channels scoped to a region containing it, and Beacon-wide config channels' in: query name: iata type: string - description: Filter by IATA code(s), comma-separated e.g. YOW or YOW,YYZ; same membership rule as iata in: query name: iatas type: string - description: Only channels Beacon can (true) or cannot (false) decrypt; omit for all in: query name: keyKnown type: boolean - description: last_seen epoch ms of last item for pagination; 0 starts from the beginning in: query name: cursor type: integer - description: Opaque nextPageCursor from a previous response; preserves timestamp ties and precision. Cannot be combined with a positive cursor; cursor=0 is allowed. in: query name: pageCursor type: string - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelPage' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List channels tags: - Channels /channels/{channelID}: get: parameters: - description: Channel integer ID in: path name: channelID required: true type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Channel' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get channel detail tags: - Channels /channels/{channelID}/messages: get: parameters: - description: Channel integer ID in: path name: channelID required: true type: integer - description: Return messages after this epoch ms in: query name: since type: integer - description: Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: 'Filter by transport scope name e.g. %23bc (URL-encoded #bc)' in: query name: scope type: string - description: Message ID of last item for pagination (results ordered newest first) in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: type: object "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List messages for a channel tags: - Channels /iatas: get: produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA' type: array "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List all IATA codes tags: - IATAs /iatas/{iata}: get: parameters: - description: 3-letter IATA code in: path name: iata required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get a single IATA code tags: - IATAs /iatas/{iata}/border: get: parameters: - description: 3-letter IATA code in: path name: iata required: true type: string produces: - application/json responses: "200": description: GeoJSON Feature (Polygon or MultiPolygon geometry, with bbox) schema: type: object "204": description: IATA exists but has no border configured "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get an IATA's GeoJSON border, if configured tags: - IATAs /messages: get: parameters: - description: Filter by channel integer ID (mutually exclusive with channelHash) in: query name: channelID type: integer - description: Filter by channel hash byte hex (mutually exclusive with channelID) in: query name: channelHash type: string - description: Return messages after this epoch ms in: query name: since type: integer - description: Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: 'Filter by transport scope name e.g. %23bc (URL-encoded #bc)' in: query name: scope type: string - description: Message ID of last item for pagination (results ordered newest first) in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: type: object "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List channel messages tags: - Messages /messages/backfill: get: parameters: - description: Return messages after this ID (use last WS event message ID) in: query name: afterId required: true type: integer - description: Filter by IATA code(s), comma-separated in: query name: iatas type: string - description: Filter by region slug in: query name: region type: string - description: Filter by region ID in: query name: regionId type: integer - description: Filter by transport scope name in: query name: scope type: string - description: Max results (default 100); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Backfill messages after a given message ID tags: - Messages /nodes: get: parameters: - description: Node type integer (1=companion, 2=repeater, 3=room_server, 4=sensor) in: query name: type type: integer - description: Node type name (companion, repeater, room_server, sensor) in: query name: typeName type: string - description: Filter by single IATA code (case-insensitive) in: query name: iata type: string - description: Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Partial case-insensitive name match in: query name: name type: string - description: 'Filter by transport scope name e.g. %23bc (URL-encoded #bc)' in: query name: scope type: string - description: Exact public key match (hex) in: query name: pubkey type: string - description: 'Partial public key match: hex prefix, case-insensitive' in: query name: pubkeyPrefix type: string - description: Filter by multibyte path support (true/false); omit for no filter in: query name: supportsMultibytePaths type: boolean - description: Filter by multibyte trace support (true/false); omit for no filter in: query name: supportsMultibyteTraces type: boolean - description: Include each node's known neighbor IDs (neighborIds field). Bare ?neighbors or ?neighbors=true enables it; omit/false for none in: query name: neighbors type: boolean - description: last_seen epoch ms of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_NodeSummary' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List nodes tags: - Nodes /nodes/{nodeId}: get: parameters: - description: Node UUID in: path name: nodeId required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Node' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get node detail tags: - Nodes /nodes/{nodeId}/neighbors: get: parameters: - description: Node UUID in: path name: nodeId required: true type: string produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List neighbors for a node tags: - Nodes /nodes/{nodeId}/observations: get: parameters: - description: Node UUID in: path name: nodeId required: true type: string - description: Observation ID of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_PacketObservationSummary' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List packet observations originating from a node tags: - Nodes /observers: get: parameters: - description: Filter by single IATA code (case-insensitive) in: query name: iata type: string - description: Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Filter by observer type (e.g. meshcoretomqtt, meshcore-ha) in: query name: type type: string - description: Filter by broker name in: query name: broker type: string - description: Filter by status (online or offline) in: query name: status type: string - description: Partial case-insensitive display name match in: query name: name type: string - description: 'Filter by transport scope name e.g. %23bc (URL-encoded #bc)' in: query name: scope type: string - description: last_seen epoch ms of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_ObserverSummary' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List observers tags: - Observers /observers/{observerId}: get: parameters: - description: Observer UUID in: path name: observerId required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Observer' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get observer detail tags: - Observers /observers/{observerId}/activity: get: parameters: - description: Observer UUID in: path name: observerId required: true type: string - description: Trailing window as a Go duration, max 720h (default 24h); max 48h when interval is under 1h in: query name: range type: string - description: 'Bucket size: 5m, 15m, 1h, 6h or 24h (default 15m)' in: query name: interval type: string - description: Optional exclusive end in epoch milliseconds; aligned down to a complete bucket, at most 30 days old. Activity uses this window; summary freshness/latestRecordedAt and the last complete hour are measured at response generation time, independently of until. in: query name: until type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivity' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get observer heard-activity history tags: - Observers /observers/{observerId}/adverts: get: parameters: - description: Observer UUID in: path name: observerId required: true type: string - description: Observation ID of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_AdvertObservation' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List advert packets heard by an observer tags: - Observers /observers/{observerId}/telemetry: get: parameters: - description: Observer UUID in: path name: observerId required: true type: string - description: Duration window e.g. 24h, 48h, 168h (default 24h) in: query name: range type: string - description: Return points after this telemetry ID for WS reconnection backfill in: query name: afterId type: integer - description: 'Bucketing interval: 1h (default), 6h, or 24h' in: query name: interval type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetry' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get observer telemetry history tags: - Observers /packets: get: parameters: - description: Filter by payload type integer in: query name: payloadType type: integer - description: Filter by multiple payload types, comma-separated e.g. 2,4 in: query name: payloadTypes type: string - description: Filter by payload type name (advert, grp_txt, txt_msg, trace, anon_req) in: query name: payloadTypeName type: string - description: Filter by route type (0=transport_flood, 1=flood, 2=direct, 3=transport_direct) in: query name: routeType type: integer - description: Filter by multiple route types, comma-separated e.g. 0,1 in: query name: routeTypes type: string - description: Filter by single IATA code (case-insensitive) in: query name: iata type: string - description: Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ in: query name: iatas type: string - description: 'Filter by transport scope name e.g. %23bc (URL-encoded #bc)' in: query name: scope type: string - description: Filter by multiple transport scope names, comma-separated e.g. %23bc,%23west in: query name: scopes type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Filter by first_heard_at >= since (epoch ms) in: query name: since type: integer - description: Filter by first_heard_at <= until (epoch ms) in: query name: until type: integer - description: epoch ms of last item for pagination; last_heard_at, or site-local heard_at when iatas is set in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: type: object "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List packets tags: - Packets /packets/{packetHash}: get: parameters: - description: Packet hash (hex) in: path name: packetHash required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Packet' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get full packet detail. For trace packets (payloadType=9), includes resolvedRoute tags: - Packets /packets/backfill: get: parameters: - description: Return packets with observations after this ID (use last WS event observation ID) in: query name: afterObservationId required: true type: integer - description: Filter by payload type integer in: query name: payloadType type: integer - description: Filter by payload type name in: query name: payloadTypeName type: string - description: Filter by route type in: query name: routeType type: integer - description: Filter by IATA code(s), comma-separated in: query name: iatas type: string - description: Filter by region slug in: query name: region type: string - description: Filter by region ID in: query name: regionId type: integer - description: Filter by transport scope name in: query name: scope type: string - description: Max results (default 100); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketSummary' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Backfill packets after a given observation ID tags: - Packets /regions: get: produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary' type: array "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List all regions tags: - Regions /regions/{regionId}: get: parameters: - description: Region ID in: path name: regionId required: true type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Region' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get a single region tags: - Regions /routes: get: parameters: - description: Filter by IATA code in: query name: iata type: string - description: Filter by exact hop count in: query name: hopCount type: integer - description: Epoch ms timestamp of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List known routes tags: - Routes /routes/{iata}/{pathKey}/observations: get: description: Matches the saved IATA, complete path bytes and hash width. Excludes TRACE and unclassified reports; other widths and search-result subsegments are not included. Byte matches do not prove hop identities or delivery. The route and its historical counter can outlive raw evidence. Cursors retain full timestamp precision and pin route/window scope. parameters: - description: Three-character IATA code in: path name: iata required: true type: string - description: Stable 32-hex pathKey from a known-route response in: path name: pathKey required: true type: string - description: Server-anchored duration (default 24h, max 720h); exclusive with since/until/pageCursor in: query name: range type: string - description: Window start epoch ms; provide with until (default last 24h) in: query name: since type: integer - description: Exclusive window end epoch ms; maximum span 30d, end may be up to 5 minutes ahead of server time (clock skew tolerance) in: query name: until type: integer - description: Opaque precise cursor from nextPageCursor; window is pinned in: query name: pageCursor type: string - description: Default 50; positive, capped at 200 in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteEvidence' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get retained reports matching a full saved route prefix sequence tags: - Routes /routes/cross: get: parameters: - description: Source node hash prefix (hex) in: query name: fromHash required: true type: string - description: Source IATA code in: query name: fromIata required: true type: string - description: Destination node hash prefix (hex) in: query name: toHash required: true type: string - description: Destination IATA code in: query name: toIata required: true type: string produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Search for routes that cross IATA boundaries tags: - Routes /routes/search: get: parameters: - description: IATA code to search within in: query name: iata required: true type: string - description: Source node hash prefix (hex) in: query name: from required: true type: string - description: Destination node hash prefix (hex) in: query name: to required: true type: string produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Search known routes by source and destination hash tags: - Routes /scopes: get: description: Without filters, lists every stored scope name, including imported names retained after an importer is disabled or a source is removed. With IATA or region filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; observed traffic does not add scopes. parameters: - description: Filter by IATA code(s), comma-separated in: query name: iatas type: string - description: Filter by region slug in: query name: region type: string - description: Filter by region ID in: query name: regionId type: integer produces: - application/json responses: "200": description: OK schema: items: type: string type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List transport scopes tags: - Scopes /scopes/{name}: get: description: packetCount sums packets per hour across every retained rollup hour; iatas are the IATAs that heard the scope's packets. Observer and node counts are current memberships. parameters: - description: 'Scope name e.g. %23bc (URL-encoded #bc)' in: path name: name required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get scope detail by name tags: - Scopes /stats/clock-drift: get: parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Max results (default 10); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Repeaters/room servers whose clock has drifted beyond the configured threshold, worst first tags: - Stats /stats/node-types: get: parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeTypeCount' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Node type breakdown tags: - Stats /stats/observations: get: description: Observation counts only; distinct packet and observer counts don't sum across IATAs, so read them from /stats/series. parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms (default 7 days ago) in: query name: since type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObservationPoint' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Hourly observation counts per IATA tags: - Stats /stats/observer-comparison: get: description: Counts distinct retained packet hashes with route type 0 or 1, using reception time in [since, until). onlyA, onlyB and both partition totalPackets (the union). Repeated receptions count once. These are reported receptions, not a measure of radio packet loss or continuous observer coverage. parameters: - description: First observer UUID in: query name: observerA required: true type: string - description: Second, distinct observer UUID in: query name: observerB required: true type: string - description: Inclusive start, epoch milliseconds (0 through 253402300799999) in: query name: since required: true type: integer - description: Exclusive end, epoch milliseconds; later than since in: query name: until required: true type: integer - description: Comma-separated reception IATA codes in: query name: iatas type: string - description: Region ID, expands to member IATAs in: query name: regionId type: integer - description: Region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverComparison' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' "503": description: Service Unavailable schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Compare flood packets reported by two observers tags: - Stats /stats/overview: get: description: Summarises the 24 most recent hours that can have been rolled (an hour rolls about 95 minutes after it closes); since/until report that window. Packets count once per hour heard. Use /stats/series for sparklines. parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsOverview' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Network overview stats (last 24 rolled hours) tags: - Stats /stats/paths: get: description: Counts stored receptions in [since, until), at most 30 days. Hash widths count only validated nonempty ordinary header paths (1/2/3 bytes). Empty paths do not vote for a width. TRACE header paths contain signal readings and are separate. Missing payload type or inconsistent/unsupported path metadata is unclassified. The four categories partition total receptions. Flood paths accumulate entries; direct paths contain remaining entries, so counts do not measure distance or a complete traversed route. Both boundaries round down to UTC hours and the response reports that effective window. Reads use materialized snapshots refreshed by background.view_refresh; the current partial hour is excluded and missing hours are omitted. parameters: - description: Inclusive start, epoch milliseconds (0 through 253402300799999) in: query name: since required: true type: integer - description: Exclusive end, epoch milliseconds; at most 30 days after since in: query name: until required: true type: integer - description: Comma-separated reception IATA codes in: query name: iatas type: string - description: Region ID, expands to member IATAs in: query name: regionId type: integer - description: Region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' "503": description: Service Unavailable schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Received path-entry and hash-width distributions tags: - Stats /stats/payload-breakdown: get: parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms (default last 24h) in: query name: since type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Observation counts by payload type (last 24h by default) tags: - Stats /stats/radio-presets: get: parameters: - description: Filter by preset string e.g. 910.525,62.5,7 in: query name: preset type: string - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Radio preset usage by IATA tags: - Stats /stats/scopes: get: description: 'Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. hourly splits packetCount by UTC hour and adds the distinct observers and advertising nodes active in the scope each hour (empty hours omitted; outage gaps come from /stats/series hour status). With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.' parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Single IATA code; used when iatas is absent in: query name: iata type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs; combined with explicit IATAs in: query name: region type: string - description: Start of packet window epoch ms, rounded down to the hour (default 7 days ago) in: query name: since type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Scope statistics tags: - Stats /stats/series: get: description: One entry per UTC hour in [since, until) plus a summary over the complete hours. Both bounds round down to UTC hours and since is clamped to the rollup retention; the response reports the effective window. An hour is rolled about 95 minutes after it closes, so recent hours are "missing" until then; "partial" hours lost raw rows before they could be rolled and never get values. Counts (observations, packets) sum across hours, with a packet counted once in each hour it was heard; observers, IATAs and scopes are distinct across the whole window; averages are sum / samples. revision changes whenever any rolled hour changes. parameters: - description: Inclusive start, epoch milliseconds in: query name: since required: true type: integer - description: Exclusive end, epoch milliseconds; the window is at most the rollup retention (default 90 days) in: query name: until required: true type: integer - description: Comma-separated reception IATA codes in: query name: iatas type: string - description: Region ID, expands to member IATAs in: query name: regionId type: integer - description: Region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeries' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' "503": description: Service Unavailable schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Hourly network activity from the analytics rollups tags: - Stats /stats/signal: get: description: Aggregates stored observer receptions in [since, until), at most 30 days. SNR is dB; RSSI is dBm. Null/non-finite readings and the zero/zero unavailable sentinel are excluded per metric; actual zero SNR with nonzero RSSI remains valid. Averages are null without samples. Histogram bounds are lower-inclusive/upper-exclusive, with null for unbounded ends. Both boundaries round down to UTC hours and the response reports that effective window. Reads use hourly materialized snapshots refreshed by background.view_refresh; the current partial hour is excluded and absent hours are omitted. These last-hop readings do not measure end-to-end quality or packet loss. parameters: - description: Inclusive start, epoch milliseconds (0 through 253402300799999) in: query name: since required: true type: integer - description: Exclusive end, epoch milliseconds; at most 30 days after since in: query name: until required: true type: integer - description: Comma-separated reception IATA codes in: query name: iatas type: string - description: Region ID, expands to member IATAs in: query name: regionId type: integer - description: Region slug, expands to member IATAs in: query name: region type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalStats' "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' "503": description: Service Unavailable schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Reception signal distributions and hourly trends tags: - Stats /stats/top-advertisers: get: description: Each advert counts once per hour heard, however many requested IATAs heard it. nodeId is null when the node row has been deleted. parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms (default last 24h) in: query name: since type: integer - description: Max results (default 10); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Top N nodes by distinct ADVERT packet count (last 24h by default) tags: - Stats /stats/top-nodes: get: description: nodeId is null when the node row has been deleted; publicKey always identifies it. parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms, rounded down to the hour (default 7 days ago) in: query name: since type: integer - description: Max results (default 10); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Top N nodes by advert hearings (last 7 days by default) tags: - Stats /stats/top-observers: get: parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms (default last 24h) in: query name: since type: integer - description: Max results (default 10); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Top N observers by observation count (last 24h by default) tags: - Stats /stats/top-talkers: get: parameters: - description: Comma-separated IATA codes in: query name: iatas type: string - description: Filter by region ID, expands to member IATAs in: query name: regionId type: integer - description: Filter by region slug, expands to member IATAs in: query name: region type: string - description: Start of window epoch ms (default last 24h) in: query name: since type: integer - description: Max results (default 10); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker' type: array "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Top N companion names by decrypted channel message count (last 24h by default) tags: - Stats /traces: get: parameters: - description: Filter by IATA code(s), comma-separated in: query name: iatas type: string - description: Filter by region slug in: query name: region type: string - description: Filter by region ID in: query name: regionId type: integer - description: Filter by the tag's first transport scope name in: query name: scope type: string - description: 'Filter by type: TRACE (any multi-hop packet) or PING (default: all)' in: query name: type type: string - description: Filter by first_heard_at >= since (epoch ms) in: query name: since type: integer - description: Filter by first_heard_at <= until (epoch ms) in: query name: until type: integer - description: last_heard_at epoch ms of last item for pagination in: query name: cursor type: integer - description: Max results (default 50); must be positive, values above 200 are clamped in: query maximum: 200 minimum: 1 name: limit type: integer produces: - application/json responses: "200": description: OK schema: items: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary' type: array "400": description: Bad Request schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: List trace tags tags: - Traces /traces/{tag}: get: parameters: - description: Trace tag hex e.g. a3f1b2c4 in: path name: tag required: true type: string produces: - application/json responses: "200": description: OK schema: $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceDetail' "404": description: Not Found schema: $ref: '#/definitions/internal_api_handlers.APIError' "500": description: Internal Server Error schema: $ref: '#/definitions/internal_api_handlers.APIError' summary: Get full trace detail by tag tags: - Traces schemes: - http - https securityDefinitions: AdminKey: description: Enter Bearer followed by the configured operator key. Use HTTPS. in: header name: Authorization type: apiKey swagger: "2.0" tags: - description: Airport/location codes that group observers and packets name: IATAs - description: Super-regions grouping multiple IATAs name: Regions - description: MeshCore MQTT observers (gateways) name: Observers - description: MeshCore radio nodes name: Nodes - description: LoRa packets heard by observers name: Packets - description: MeshCore group text channels name: Channels - description: Decrypted channel messages name: Messages - description: MQTT broker connection status name: Brokers - description: Network statistics and time series name: Stats