dandri/beacon-server
1
0
Fork 0
mirror of https://github.com/MeshCore-Beacon/beacon-server.git synced 2026-10-20 18:02:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
ced19727ea44efa21ecb24c2eecbb00af2472eec
beacon-server/docs/swagger.yaml
T

4056 lines
124 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
github_com_MeshCore-Beacon_beacon-server_internal_meshmapper.CatalogueScope:
properties:
default:
type: integer
monitored:
type: boolean
name:
type: string
repeaters:
type: integer
wardriving:
type: boolean
type: object
github_com_MeshCore-Beacon_beacon-server_internal_meshmapper.PublicScopeCatalogue:
properties:
checkedAt:
type: integer
freshUntil:
type: integer
generatedAt:
type: integer
iata:
type: string
lastError:
type: string
repeaters:
type: integer
scoped:
type: integer
scopes:
items:
$ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_meshmapper.CatalogueScope'
type: array
url:
type: string
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 one complete path representation in the saved IATA. Defaults
to the latest processed prefixes; hashSize/pathBytes pin a prior response.
Excludes TRACE and unclassified reports; widths are never combined. Pinned
prefixes must match the saved node chain or its current metadata. Byte matches
do not prove hop identities or delivery. The route counter can outlive raw
evidence. New cursors pin path, route, window and full timestamp precision;
legacy unpinned cursors remain supported.
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: Exact hash width (1–3); provide with pathBytes to pin a response's
representation
in: query
maximum: 3
minimum: 1
name: hashSize
type: integer
- description: Complete lower-case hex path from the response; provide with
hashSize
in: query
name: pathBytes
type: string
- description: Opaque precise cursor from nextPageCursor; route, window and
path are 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
/scope-catalogues:
get:
description: Discovered sources only. Counts describe the source region, not
individual nodes or links. No upstream request is made. An empty list means
no configured importer; checkedAt=0 means no successful check. lastError or
a past freshUntil marks stale metadata. Manual Beacon scopes and packet evidence
are separate.
produces:
- application/json
responses:
"200":
description: OK
schema:
items:
$ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_meshmapper.PublicScopeCatalogue'
type: array
summary: Cached MeshMapper regional scope catalogues
tags:
- Scopes
/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
Reference in New Issue View Git Blame Copy Permalink