dandri/beacon-server
1
0
Fork 0
mirror of https://github.com/MeshCore-Beacon/beacon-server.git synced 2026-10-16 13:49:56 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5fbba24a4a8a3d97c87c4a88b60bbeacf7bbc68f
beacon-server/docs/docs.go
T

5342 lines
202 KiB
Go
Raw Blame History

// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
import "github.com/swaggo/swag"
const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"termsOfService": "https://github.com/MeshCore-Beacon/beacon-server",
"contact": {
"name": "MeshCore Beacon",
"url": "https://github.com/MeshCore-Beacon/beacon-server"
},
"license": {
"name": "AGPL-3-or-later"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/admin/accounts": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Includes active and inactive accounts, newest first. These records are not login users.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "List operator accounts",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"post": {
"security": [
{
"AdminKey": []
}
],
"description": "Trims the name; names are case-sensitive and unique among active accounts. No credential or login is created.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Create an operator account",
"parameters": [
{
"description": "Account name (1-128 Unicode characters, no control characters); body at most 4 KiB",
"name": "account",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"413": {
"description": "Request Entity Too Large",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"415": {
"description": "Unsupported Media Type",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/accounts/{id}": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Returns active or inactive account records.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Get an operator account",
"parameters": [
{
"type": "string",
"format": "uuid",
"description": "Account UUID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"delete": {
"security": [
{
"AdminKey": []
}
],
"description": "Soft deactivation preserves the record. Its name may be reused by a new account.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Deactivate an operator account",
"parameters": [
{
"type": "string",
"format": "uuid",
"description": "Account UUID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "Deactivated"
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/backup": {
"get": {
"security": [
{
"AdminKey": []
}
],
"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"
],
"tags": [
"Admin"
],
"summary": "Download a private database and saved-config backup",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "file"
},
"headers": {
"Content-Disposition": {
"type": "string",
"description": "attachment; filename=beacon-backup.tar.gz"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"504": {
"description": "Gateway Timeout",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"507": {
"description": "Insufficient Storage",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/config": {
"get": {
"security": [
{
"AdminKey": []
}
],
"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"
],
"tags": [
"Admin"
],
"summary": "Inspect selected running configuration",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"put": {
"security": [
{
"AdminKey": []
}
],
"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.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Update runtime CORS origins",
"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.",
"name": "config",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"413": {
"description": "Request Entity Too Large",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"415": {
"description": "Unsupported Media Type",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/brokers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Brokers"
],
"summary": "List all MQTT brokers and their connection status",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api_handlers.BrokerStatus"
}
}
}
}
}
},
"/channels": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "List channels",
"parameters": [
{
"type": "string",
"description": "Single-byte channel hash (hex)",
"name": "hash",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YOW or YOW,YYZ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination; 0 starts from the beginning",
"name": "cursor",
"in": "query"
},
{
"type": "string",
"description": "Opaque nextPageCursor from a previous response; preserves timestamp ties and precision. Cannot be combined with a positive cursor; cursor=0 is allowed.",
"name": "pageCursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/channels/{channelID}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "Get channel detail",
"parameters": [
{
"type": "integer",
"description": "Channel integer ID",
"name": "channelID",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/channels/{channelID}/messages": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "List messages for a channel",
"parameters": [
{
"type": "integer",
"description": "Channel integer ID",
"name": "channelID",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Return messages after this epoch ms",
"name": "since",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "Message ID of last item for pagination (results ordered newest first)",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/iatas": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "List all IATA codes",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/iatas/{iata}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "Get a single IATA code",
"parameters": [
{
"type": "string",
"description": "3-letter IATA code",
"name": "iata",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/iatas/{iata}/border": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "Get an IATA's GeoJSON border, if configured",
"parameters": [
{
"type": "string",
"description": "3-letter IATA code",
"name": "iata",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/messages": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "List channel messages",
"parameters": [
{
"type": "integer",
"description": "Filter by channel integer ID (mutually exclusive with channelHash)",
"name": "channelID",
"in": "query"
},
{
"type": "string",
"description": "Filter by channel hash byte hex (mutually exclusive with channelID)",
"name": "channelHash",
"in": "query"
},
{
"type": "integer",
"description": "Return messages after this epoch ms",
"name": "since",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "Message ID of last item for pagination (results ordered newest first)",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/messages/backfill": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "Backfill messages after a given message ID",
"parameters": [
{
"type": "integer",
"description": "Return messages after this ID (use last WS event message ID)",
"name": "afterId",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name",
"name": "scope",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 100); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List nodes",
"parameters": [
{
"type": "integer",
"description": "Node type integer (1=companion, 2=repeater, 3=room_server, 4=sensor)",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "Node type name (companion, repeater, room_server, sensor)",
"name": "typeName",
"in": "query"
},
{
"type": "string",
"description": "Filter by single IATA code (case-insensitive)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Partial case-insensitive name match",
"name": "name",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Exact public key match (hex)",
"name": "pubkey",
"in": "query"
},
{
"type": "string",
"description": "Partial public key match: hex prefix, case-insensitive",
"name": "pubkeyPrefix",
"in": "query"
},
{
"type": "boolean",
"description": "Filter by multibyte path support (true/false); omit for no filter",
"name": "supportsMultibytePaths",
"in": "query"
},
{
"type": "boolean",
"description": "Filter by multibyte trace support (true/false); omit for no filter",
"name": "supportsMultibyteTraces",
"in": "query"
},
{
"type": "boolean",
"description": "Include each node's known neighbor IDs (neighborIds field). Bare ?neighbors or ?neighbors=true enables it; omit/false for none",
"name": "neighbors",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/nodes/{nodeId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "Get node detail",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/nodes/{nodeId}/neighbors": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List neighbors for a node",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes/{nodeId}/observations": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List packet observations originating from a node",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Observation ID of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/observers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "List observers",
"parameters": [
{
"type": "string",
"description": "Filter by single IATA code (case-insensitive)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by observer type (e.g. meshcoretomqtt, meshcore-ha)",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "Filter by broker name",
"name": "broker",
"in": "query"
},
{
"type": "string",
"description": "Filter by status (online or offline)",
"name": "status",
"in": "query"
},
{
"type": "string",
"description": "Partial case-insensitive display name match",
"name": "name",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/observers/{observerId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "Get observer detail",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/observers/{observerId}/activity": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "Get observer heard-activity history",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Trailing window as a Go duration, max 720h (default 24h); max 48h when interval is under 1h",
"name": "range",
"in": "query"
},
{
"type": "string",
"description": "Bucket size: 5m, 15m, 1h, 6h or 24h (default 15m)",
"name": "interval",
"in": "query"
},
{
"type": "integer",
"description": "Optional exclusive end in epoch milliseconds; aligned down to a complete bucket, at most 30 days old",
"name": "until",
"in": "query"
}
],
"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"
}
}
}
}
},
"/observers/{observerId}/adverts": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "List advert packets heard by an observer",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Observation ID of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/observers/{observerId}/telemetry": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "Get observer telemetry history",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Duration window e.g. 24h, 48h, 168h (default 24h)",
"name": "range",
"in": "query"
},
{
"type": "integer",
"description": "Return points after this telemetry ID for WS reconnection backfill",
"name": "afterId",
"in": "query"
},
{
"type": "string",
"description": "Bucketing interval: 1h (default), 6h, or 24h",
"name": "interval",
"in": "query"
}
],
"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"
}
}
}
}
},
"/packets": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Packets"
],
"summary": "List packets",
"parameters": [
{
"type": "integer",
"description": "Filter by payload type integer",
"name": "payloadType",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple payload types, comma-separated e.g. 2,4",
"name": "payloadTypes",
"in": "query"
},
{
"type": "string",
"description": "Filter by payload type name (advert, grp_txt, txt_msg, trace, anon_req)",
"name": "payloadTypeName",
"in": "query"
},
{
"type": "integer",
"description": "Filter by route type (0=transport_flood, 1=flood, 2=direct, 3=transport_direct)",
"name": "routeType",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple route types, comma-separated e.g. 0,1",
"name": "routeTypes",
"in": "query"
},
{
"type": "string",
"description": "Filter by single IATA code (case-insensitive)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple transport scope names, comma-separated e.g. %23bc,%23west",
"name": "scopes",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003e= since (epoch ms)",
"name": "since",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003c= until (epoch ms)",
"name": "until",
"in": "query"
},
{
"type": "integer",
"description": "epoch ms of last item for pagination; last_heard_at, or site-local heard_at when iatas is set",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"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"
}
}
}
}
},
"/packets/backfill": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Packets"
],
"summary": "Backfill packets after a given observation ID",
"parameters": [
{
"type": "integer",
"description": "Return packets with observations after this ID (use last WS event observation ID)",
"name": "afterObservationId",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Filter by payload type integer",
"name": "payloadType",
"in": "query"
},
{
"type": "string",
"description": "Filter by payload type name",
"name": "payloadTypeName",
"in": "query"
},
{
"type": "integer",
"description": "Filter by route type",
"name": "routeType",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name",
"name": "scope",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 100); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketSummary"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/packets/{packetHash}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Packets"
],
"summary": "Get full packet detail. For trace packets (payloadType=9), includes resolvedRoute",
"parameters": [
{
"type": "string",
"description": "Packet hash (hex)",
"name": "packetHash",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/regions": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Regions"
],
"summary": "List all regions",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/regions/{regionId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Regions"
],
"summary": "Get a single region",
"parameters": [
{
"type": "integer",
"description": "Region ID",
"name": "regionId",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/routes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "List known routes",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code",
"name": "iata",
"in": "query"
},
{
"type": "integer",
"description": "Filter by exact hop count",
"name": "hopCount",
"in": "query"
},
{
"type": "integer",
"description": "Epoch ms timestamp of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/cross": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search for routes that cross IATA boundaries",
"parameters": [
{
"type": "string",
"description": "Source node hash prefix (hex)",
"name": "fromHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Source IATA code",
"name": "fromIata",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex)",
"name": "toHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination IATA code",
"name": "toIata",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/search": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search known routes by source and destination hash",
"parameters": [
{
"type": "string",
"description": "IATA code to search within",
"name": "iata",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Source node hash prefix (hex)",
"name": "from",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex)",
"name": "to",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/scopes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Scopes"
],
"summary": "List transport scopes",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/scopes/{name}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Scopes"
],
"summary": "Get scope detail by name",
"parameters": [
{
"type": "string",
"description": "Scope name e.g. %23bc (URL-encoded #bc)",
"name": "name",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
},
"/stats/clock-drift": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Repeaters/room servers whose clock has drifted beyond the configured threshold, worst first",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/node-types": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Node type breakdown",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeTypeCount"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/observations": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Hourly observation time series",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default 7 days ago)",
"name": "since",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObservationPoint"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/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.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Compare flood packets reported by two observers",
"parameters": [
{
"type": "string",
"description": "First observer UUID",
"name": "observerA",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Second, distinct observer UUID",
"name": "observerB",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; later than since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"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"
}
}
}
}
},
"/stats/overview": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Network overview stats (last 24h)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"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"
}
}
}
}
},
"/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.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Received path-entry and hash-width distributions",
"parameters": [
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; at most 30 days after since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"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"
}
}
}
}
},
"/stats/payload-breakdown": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Observation counts by payload type (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/radio-presets": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Radio preset usage by IATA",
"parameters": [
{
"type": "string",
"description": "Filter by preset string e.g. 910.525,62.5,7",
"name": "preset",
"in": "query"
},
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/scopes": {
"get": {
"description": "Counts each packet, observer and node once per scope. IATA filters use retained observations for packets/observers and node IATA memberships for nodes. Without filters, returns global totals. Scopes with zero matching counts remain listed; an empty region returns an empty array.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Scope statistics",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Single IATA code; used when iatas is absent",
"name": "iata",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs; combined with explicit IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/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.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Reception signal distributions and hourly trends",
"parameters": [
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; at most 30 days after since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"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"
}
}
}
}
},
"/stats/top-advertisers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N nodes by distinct ADVERT packet count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-nodes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N nodes by observation count (from materialized view)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-observers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N observers by observation count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-talkers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N companion names by decrypted channel message count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/traces": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Traces"
],
"summary": "List trace tags",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Filter by type: TRACE or PING (default: all)",
"name": "type",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003e= since (epoch ms)",
"name": "since",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003c= until (epoch ms)",
"name": "until",
"in": "query"
},
{
"type": "integer",
"description": "last_heard_at epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/traces/{tag}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Traces"
],
"summary": "Get full trace detail by tag",
"parameters": [
{
"type": "string",
"description": "Trace tag hex e.g. a3f1b2c4",
"name": "tag",
"in": "path",
"required": true
}
],
"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"
}
}
}
}
}
},
"definitions": {
"github_com_MeshCore-Beacon_beacon-server_internal_api.Account": {
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"deactivated_at": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminAuthConfig": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminCORSConfig": {
"type": "object",
"properties": {
"allow_credentials": {
"type": "boolean"
},
"allowed_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"allowed_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"allowed_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"max_age": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminIngestConfig": {
"type": "object",
"properties": {
"broker_count": {
"description": "BrokerCount counts configured broker workers, not active MQTT connections\nor a configurable processing-worker pool.",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Channel": {
"type": "object",
"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": {
"type": "integer"
},
"name": {
"description": "display name from config or nil",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage": {
"type": "object",
"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"
},
"senderName": {
"description": "display name from the decrypted payload",
"type": "string"
},
"sentAt": {
"description": "epoch ms, from the sender's embedded timestamp",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelPage": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary"
}
},
"nextCursor": {
"type": "integer"
},
"nextPageCursor": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry": {
"type": "object",
"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",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA"
}
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop": {
"type": "object",
"properties": {
"fromIata": {
"type": "string"
},
"fromNode": {
"description": "last node in source IATA",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
]
},
"lastSeen": {
"description": "epoch ms",
"type": "integer"
},
"toIata": {
"type": "string"
},
"toNode": {
"description": "first node in target IATA",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
]
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute": {
"type": "object",
"properties": {
"crossHop": {
"description": "the boundary hop",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop"
}
]
},
"sourceSegment": {
"description": "route segment in source IATA",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"targetSegment": {
"description": "route segment in target IATA",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"totalHops": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.IATA": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"lat": {
"type": "number"
},
"lon": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute": {
"type": "object",
"properties": {
"firstSeen": {
"description": "epoch ms",
"type": "integer"
},
"hopCount": {
"type": "integer"
},
"hops": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"iata": {
"type": "string"
},
"id": {
"type": "integer"
},
"lastSeen": {
"description": "epoch ms",
"type": "integer"
},
"observationCount": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Node": {
"type": "object",
"properties": {
"clockCheckedAt": {
"type": "integer"
},
"clockDriftSeconds": {
"description": "Clock drift, repeaters/room servers only (nodeType 2/3); omitted entirely for other\nnode types or when no qualifying advert has been measured yet. Device minus server\ntime, in seconds, from the advert's self-reported timestamp: +ve = device ahead.\nclockCheckedAt is the server receive time of the advert this was measured from (same\nmoment as lastAdvertAt). clockOutOfSync is |clockDriftSeconds| exceeding a configured\nthreshold (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",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA"
}
},
"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",
"type": "array",
"items": {
"type": "string"
}
},
"neighbors": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor"
}
},
"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\nconfigured 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\nstaleness window (default 24h; internal/config.ResolvedConfig.NodeStaleThreshold).\nApplies to every node type, unlike ClockDriftSeconds/ClockOutOfSync on Node, which\nare repeater/room-server only.",
"type": "boolean"
},
"supportsMultibytePaths": {
"description": "firmware \u003e= 1.14.0; detected via path hash size",
"type": "boolean"
},
"supportsMultibyteTraces": {
"description": "firmware \u003e= 1.11.0; detected via trace hash size",
"type": "boolean"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA": {
"type": "object",
"properties": {
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.NodeSummary": {
"type": "object",
"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",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA"
}
},
"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",
"type": "array",
"items": {
"type": "string"
}
},
"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\nconfigured 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\nstaleness window (default 24h; internal/config.ResolvedConfig.NodeStaleThreshold).\nApplies to every node type, unlike ClockDriftSeconds/ClockOutOfSync on Node, which\nare repeater/room-server only.",
"type": "boolean"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.NodeTypeCount": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObservationPoint": {
"type": "object",
"properties": {
"activeObservers": {
"type": "integer"
},
"hour": {
"description": "epoch ms, start of the 1-hour bucket",
"type": "integer"
},
"iata": {
"type": "string"
},
"observationCount": {
"type": "integer"
},
"uniquePackets": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Observer": {
"type": "object",
"properties": {
"batteryLevel": {
"description": "volts, nil if mains powered",
"type": "number"
},
"brokers": {
"description": "broker names this observer has been seen on",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverBroker"
}
},
"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",
"type": "array",
"items": {
"type": "string"
}
},
"softwareVersion": {
"type": "string"
},
"status": {
"description": "\"online\" or \"offline\" derived from last_status_at",
"type": "string"
},
"statusMetadata": {
"description": "raw /status JSON payload"
},
"uptimeSeconds": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivity": {
"type": "object",
"properties": {
"generatedAt": {
"description": "response computation time, not proof of continuous coverage",
"type": "integer"
},
"interval": {
"type": "string"
},
"payloadTypes": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem"
}
},
"points": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityPoint"
}
},
"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 complete-bucket end, epoch ms",
"type": "integer"
},
"windowStart": {
"description": "inclusive complete-bucket start, epoch ms",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityPoint": {
"type": "object",
"properties": {
"airtimeMs": {
"type": "number"
},
"observations": {
"type": "integer"
},
"rssiAvg": {
"type": "number"
},
"snrAvg": {
"type": "number"
},
"snrMin": {
"type": "number"
},
"t": {
"description": "bucket start, epoch ms",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityRadio": {
"type": "object",
"properties": {
"bwKhz": {
"type": "number"
},
"cr": {
"type": "integer"
},
"freqMhz": {
"type": "number"
},
"preambleSymbols": {
"type": "integer"
},
"sf": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivitySummary": {
"type": "object",
"properties": {
"lastCompleteHour": {
"type": "integer"
},
"lastCompleteHourEnd": {
"type": "integer"
},
"lastCompleteHourStart": {
"type": "integer"
},
"latestRecordedAt": {
"type": "integer"
},
"recordedPackets": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverBroker": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverComparison": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverSummary": {
"type": "object",
"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",
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"description": "\"online\" or \"offline\" derived from last_status_at",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetry": {
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"points": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint"
}
},
"range": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Packet": {
"type": "object",
"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": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail"
}
},
"originPubkey": {
"description": "hex-encoded; nil when not extractable from payload",
"type": "string"
},
"packetHash": {
"type": "string"
},
"parsedPayload": {
"type": "array",
"items": {
"type": "integer"
}
},
"rawPayload": {
"description": "hex-encoded payload bytes (excludes header and path)",
"type": "string"
},
"resolvedRoute": {
"description": "trace packets only: resolved intended route",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"scope": {
"description": "matched transport scope name e.g. \"#bc\"",
"type": "string"
},
"transportCodes": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketHeader": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketLatestObserver": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"id": {
"type": "string"
},
"pathBytes": {
"description": "hex-encoded accumulated path hashes",
"type": "string"
},
"pathLength": {
"description": "PathLength/PathBytes and captured endpoint resolutions are stored on the observation,\nso list/backfill reads need no per-hash resolution queries. Legacy observations have\nno endpoint snapshot. ResolvedPath remains a detail/opted-in WS feature.",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength"
}
]
},
"resolvedDestination": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
},
"resolvedPath": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"resolvedSource": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail": {
"type": "object",
"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",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"resolvedSource": {
"description": "ResolvedSource/ResolvedDestination are the packet's endpoints, when the payload type\ncarries one. Prefer the snapshot captured at ingest; legacy observations without a\nsnapshot use the current node registry. Endpoint matching itself is unchanged:\nan exact match for ADVERT's full pubkey, an ambiguous\nhash-prefix match (like intermediate hops) for TEXT_MESSAGE/PATH/ANON_REQ's 1-byte\nsource/destination hashes. Nil when the payload type doesn't carry one at all (e.g.\nGRP_TXT/GRP_DATA/TRACE aren't node-to-node addressed) -- see BuildResolvedPath and\nResolveExactNode for how each is built.",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
]
},
"rssi": {
"type": "integer"
},
"snr": {
"type": "number"
},
"sourceBroker": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketRadio": {
"type": "object",
"properties": {
"bandwidthKhz": {
"type": "number"
},
"codingRate": {
"type": "integer"
},
"freqMhz": {
"type": "number"
},
"spreadFactor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketSummary": {
"type": "object",
"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 from this packet; omitted when unavailable or unsupported",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes": {
"type": "object",
"properties": {
"regionCode": {
"type": "integer"
},
"subRegionCode": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_AdvertObservation": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_NodeSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_ObserverSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_PacketObservationSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth": {
"type": "object",
"properties": {
"bytes": {
"type": "integer"
},
"receptions": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour": {
"type": "object",
"properties": {
"empty": {
"type": "integer"
},
"hour": {
"type": "integer"
},
"oneByte": {
"type": "integer"
},
"receptions": {
"type": "integer"
},
"threeByte": {
"type": "integer"
},
"trace": {
"type": "integer"
},
"twoByte": {
"type": "integer"
},
"unclassified": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin": {
"type": "object",
"properties": {
"entries": {
"type": "integer"
},
"receptions": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats": {
"type": "object",
"properties": {
"empty": {
"type": "integer"
},
"hashWidths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth"
}
},
"hashed": {
"type": "integer"
},
"hourly": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour"
}
},
"pathLengths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin"
}
},
"receptions": {
"type": "integer"
},
"since": {
"type": "integer"
},
"trace": {
"type": "integer"
},
"unclassified": {
"type": "integer"
},
"until": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset": {
"type": "object",
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop": {
"type": "object",
"properties": {
"hash": {
"description": "hex-encoded path hash",
"type": "string"
},
"snr": {
"description": "signal-to-noise ratio in dB, if available",
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Region": {
"type": "object",
"properties": {
"centerLat": {
"description": "map center latitude",
"type": "number"
},
"centerLng": {
"description": "map center longitude",
"type": "number"
},
"description": {
"type": "string"
},
"iatas": {
"description": "member IATA codes",
"type": "array",
"items": {
"type": "string"
}
},
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"slug": {
"description": "URL-safe identifier e.g. \"western-canada\"",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop": {
"type": "object",
"properties": {
"confidence": {
"description": "\"high\", \"ambiguous\", or \"none\"",
"type": "string"
},
"nodes": {
"description": "empty for \"none\", one for \"high\", multiple for \"ambiguous\"",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
},
"snr": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"name": {
"type": "string"
},
"publicKey": {
"description": "hex-encoded prefix used for resolution",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop": {
"type": "object",
"properties": {
"hashBytes": {
"description": "hex-encoded hash prefix",
"type": "string"
},
"node": {
"description": "populated when node details are available",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
]
},
"nodeId": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail": {
"type": "object",
"properties": {
"iataCount": {
"type": "integer"
},
"iatas": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string"
},
"nodeCount": {
"type": "integer"
},
"observerCount": {
"type": "integer"
},
"packetCount": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats": {
"type": "object",
"properties": {
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"lower": {
"type": "number"
},
"upper": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour": {
"type": "object",
"properties": {
"hour": {
"type": "integer"
},
"receptions": {
"type": "integer"
},
"rssiAverage": {
"type": "number"
},
"rssiSamples": {
"type": "integer"
},
"snrAverage": {
"type": "number"
},
"snrSamples": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric": {
"type": "object",
"properties": {
"average": {
"type": "number"
},
"histogram": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin"
}
},
"samples": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalStats": {
"type": "object",
"properties": {
"hourly": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour"
}
},
"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"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.StatsOverview": {
"type": "object",
"properties": {
"activeIatas": {
"type": "integer"
},
"activeObservers": {
"type": "integer"
},
"totalObservations": {
"type": "integer"
},
"totalPackets": {
"type": "integer"
},
"windowHours": {
"description": "always 24 for now",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser": {
"type": "object",
"properties": {
"advertCount": {
"type": "integer"
},
"directAdvertCount": {
"type": "integer"
},
"floodAdvertCount": {
"description": "FloodAdvertCount/DirectAdvertCount split AdvertCount by how the advert was routed:\nflood = route type 0 (transport_flood) or 1 (flood), broadcast with no known path;\ndirect = route type 2 (direct) or 3 (transport_direct), routed along a known path.\nFloodAdvertCount + DirectAdvertCount == AdvertCount.",
"type": "integer"
},
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode": {
"type": "object",
"properties": {
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
},
"observationCount": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"observationCount": {
"type": "integer"
},
"observerId": {
"type": "string"
},
"observerType": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker": {
"type": "object",
"properties": {
"lastSent": {
"description": "epoch ms",
"type": "integer"
},
"messageCount": {
"type": "integer"
},
"senderName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TraceDetail": {
"type": "object",
"properties": {
"packets": {
"description": "all packets observed for this trace",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket"
}
},
"traceTag": {
"description": "hex-encoded 4-byte tag",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket": {
"type": "object",
"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",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop"
}
},
"resolvedRoute": {
"description": "hops resolved to known nodes",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"routeType": {
"description": "numeric route type",
"type": "integer"
},
"routeTypeName": {
"description": "human-readable route type",
"type": "string"
},
"scope": {
"description": "transport scope name, if known",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary": {
"type": "object",
"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",
"type": "array",
"items": {
"type": "string"
}
},
"snrValues": {
"description": "SNR per hop from the most complete observation",
"type": "array",
"items": {
"type": "number"
}
},
"traceTag": {
"description": "hex-encoded 4-byte tag",
"type": "string"
},
"traceType": {
"description": "TRACE or PING",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest": {
"type": "object",
"required": [
"allowed_origins"
],
"properties": {
"allowed_origins": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest": {
"type": "object",
"required": [
"cors"
],
"properties": {
"cors": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse": {
"type": "object",
"properties": {
"config": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig"
},
"persisted": {
"type": "boolean"
},
"requires_restart": {
"type": "boolean"
}
}
},
"internal_api_handlers.APIError": {
"type": "object",
"properties": {
"code": {
"description": "e.g. \"not_found\", \"bad_request\"",
"type": "string"
},
"message": {
"description": "e.g. \"channel not found\"",
"type": "string"
}
}
},
"internal_api_handlers.BrokerStatus": {
"type": "object",
"properties": {
"connected": {
"type": "boolean"
},
"name": {
"type": "string"
}
}
}
},
"securityDefinitions": {
"AdminKey": {
"description": "Enter Bearer followed by the configured operator key. Use HTTPS.",
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"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"
}
]
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "1.6.0",
Host: "localhost:8080",
BasePath: "/api/v1",
Schemes: []string{"http", "https"},
Title: "MeshCore Beacon API",
Description: "MeshCore network observation backend. Ingests LoRa packets from MQTT brokers, stores in PostgreSQL, and streams live events via WebSocket.\nREST 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.\nWebSocket 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.",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
RightDelim: "}}",
}
func init() {
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
Reference in New Issue View Git Blame Copy Permalink