dandri/beacon-server
1
0
Fork 0
mirror of https://github.com/MeshCore-Beacon/beacon-server.git synced 2026-10-15 22:39:56 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
9bbf8efee553fbd67371b4e48cf0aae88b4f9834
beacon-server/docs/docs.go
T
MrAlders0n 9bbf8efee5 release: v2.0.4 (#217) 
* perf(routes): batch cross-IATA and hash route search (#216)

One search fired a /routes/cross request per IATA pair (138k on 2026-10-08). Route search now takes an optional iatas list and runs a fixed number of index-backed queries. /info advertises built-in minimum client versions.

* chore: bump version to 2.0.4
2026-10-09 22:17:23 -04:00

6144 lines
236 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: channels MeshMapper lists there, config channels scoped to a region containing it, and Beacon-wide config channels",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YOW or YOW,YYZ; same membership rule as iata",
"name": "iatas",
"in": "query"
},
{
"type": "boolean",
"description": "Only channels Beacon can (true) or cannot (false) decrypt; omit for all",
"name": "keyKnown",
"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"
}
},
"500": {
"description": "Internal Server Error",
"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"
}
}
},
"500": {
"description": "Internal Server Error",
"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"
}
},
"500": {
"description": "Internal Server Error",
"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"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/info": {
"get": {
"description": "minAppVersion (BEACON Mobile) and minWebVersion (Beacon Web) are null when the\nserver sets no requirement. Each is the higher of the built-in floor and config.",
"produces": [
"application/json"
],
"tags": [
"Info"
],
"summary": "Server info and minimum client versions",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Info"
}
}
}
}
},
"/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"
}
},
"500": {
"description": "Internal Server Error",
"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/directory": {
"get": {
"description": "Defaults to the trailing seven days through request time. Counts combine completed whole-hour analytics with retained observations for other hours and exact boundary slices. Incomplete history still returns numeric counts and the requested sort; coverage describes available history. Repeat filters and the returned windowStart/windowEnd as since/until with the cursor on later pages. Results may move as data changes; refresh without bounds for a new rolling window.",
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "List observers with windowed traffic counts",
"parameters": [
{
"type": "string",
"description": "Single IATA",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Comma-separated IATAs",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Observer type",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "Broker membership",
"name": "broker",
"in": "query"
},
{
"type": "string",
"description": "online or offline",
"name": "status",
"in": "query"
},
{
"type": "string",
"description": "Case-insensitive partial name",
"name": "name",
"in": "query"
},
{
"type": "string",
"description": "Transport scope membership",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "traffic (default) or name",
"name": "sort",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Inclusive epoch ms, preserved exactly; default seven days before until; maximum window 31 days",
"name": "since",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "Exclusive epoch ms, preserved exactly; default request time",
"name": "until",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "nextCursor returned by preceding page",
"name": "cursor",
"in": "query"
},
{
"type": "integer",
"description": "Page size, default 50, maximum 200",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverDirectory"
}
},
"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"
}
},
"500": {
"description": "Internal Server Error",
"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. Activity uses this window; summary freshness/latestRecordedAt and the last complete hour are measured at response generation time, independently of until.",
"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"
}
}
},
"500": {
"description": "Internal Server Error",
"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"
}
},
"500": {
"description": "Internal Server Error",
"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"
},
{
"type": "integer",
"description": "id of the last item; with cursor, also returns later routes sharing that millisecond",
"name": "cursorId",
"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": {
"description": "Pass iatas (comma-separated, optional; omitted searches every IATA) or the\nsingle directed pair fromIata/toIata, not both.",
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search for routes that cross IATA boundaries",
"parameters": [
{
"type": "string",
"description": "Source node hash prefix (hex, 1-4 bytes)",
"name": "fromHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex, 1-4 bytes)",
"name": "toHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated IATA codes to search (2-100)",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Source IATA code (with toIata)",
"name": "fromIata",
"in": "query"
},
{
"type": "string",
"description": "Destination IATA code (with fromIata)",
"name": "toIata",
"in": "query"
}
],
"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"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/search": {
"get": {
"description": "Routes within one IATA that run from the source hash to the destination hash,\ntrimmed to that span. iatas is optional (omitted searches every IATA); the single\niata is still accepted. At most 500, shortest first.",
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search known routes by source and destination hash",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes to search (max 100)",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Single IATA code (when iatas is omitted)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Source node hash prefix (hex, 1-4 bytes)",
"name": "from",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex, 1-4 bytes)",
"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"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/{iata}/{pathKey}/observations": {
"get": {
"description": "Matches the saved IATA, complete path bytes and hash width. Excludes TRACE and unclassified reports; other widths and search-result subsegments are not included. Byte matches do not prove hop identities or delivery. The route and its historical counter can outlive raw evidence. Cursors retain full timestamp precision and pin route/window scope.",
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Get retained reports matching a full saved route prefix sequence",
"parameters": [
{
"type": "string",
"description": "Three-character IATA code",
"name": "iata",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Stable 32-hex pathKey from a known-route response",
"name": "pathKey",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Server-anchored duration (default 24h, max 720h); exclusive with since/until/pageCursor",
"name": "range",
"in": "query"
},
{
"type": "integer",
"description": "Window start epoch ms; provide with until (default last 24h)",
"name": "since",
"in": "query"
},
{
"type": "integer",
"description": "Exclusive window end epoch ms; maximum span 30d, end may be up to 5 minutes ahead of server time (clock skew tolerance)",
"name": "until",
"in": "query"
},
{
"type": "string",
"description": "Opaque precise cursor from nextPageCursor; window is pinned",
"name": "pageCursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Default 50; positive, capped at 200",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteEvidence"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/scopes": {
"get": {
"description": "Without filters, lists every stored scope name, including imported names retained after an importer is disabled or a source is removed. With IATA or region filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; observed traffic does not add scopes.",
"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": "array",
"items": {
"type": "string"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/scopes/{name}": {
"get": {
"description": "packetCount sums packets per hour across every retained rollup hour; iatas are the IATAs that heard the scope's packets. Observer and node counts are current memberships.",
"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": {
"description": "Observation counts only; distinct packet and observer counts don't sum across IATAs, so read them from /stats/series.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Hourly observation counts per IATA",
"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": {
"description": "Summarises the 24 most recent hours that can have been rolled (an hour rolls about 95 minutes after it closes); since/until report that window. Packets count once per hour heard. Use /stats/series for sparklines.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Network overview stats (last 24 rolled hours)",
"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 the hourly path rollup; an hour appears only after it is rolled, about 95 minutes after it ends, and hours without data 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": "Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. hourly splits packetCount by UTC hour and adds the distinct observers and advertising nodes active in the scope each hour (empty hours omitted; outage gaps come from /stats/series hour status). With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.",
"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"
},
{
"type": "integer",
"description": "Start of packet window epoch ms, rounded down to the hour (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.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/series": {
"get": {
"description": "One entry per UTC hour in [since, until) plus a summary over the complete hours. Both bounds round down to UTC hours and since is clamped to the rollup retention; the response reports the effective window. An hour is rolled about 95 minutes after it closes, so recent hours are \"missing\" until then; \"partial\" hours lost raw rows before they could be rolled and never get values. Counts (observations, packets) sum across hours, with a packet counted once in each hour it was heard; observers, IATAs and scopes are distinct across the whole window; averages are sum / samples. revision changes whenever any rolled hour changes.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Hourly network activity from the analytics rollups",
"parameters": [
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; the window is at most the rollup retention (default 90 days)",
"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.StatsSeries"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/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 the hourly signal rollup; an hour appears only after it is rolled, about 95 minutes after it ends, and hours without data 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": {
"description": "Each advert counts once per hour heard, however many requested IATAs heard it. nodeId is null when the node row has been deleted.",
"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": {
"description": "nodeId is null when the node row has been deleted; publicKey always identifies it.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N nodes by advert hearings (last 7 days 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, rounded down to the hour (default 7 days ago)",
"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.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 the tag's first transport scope name",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Filter by type: TRACE (any multi-hop packet) 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": "lastHeardAt (epoch ms) of the last item; returns older tags",
"name": "cursor",
"in": "query"
},
{
"type": "string",
"description": "traceTag (hex) of the last item; with cursor, also returns later tags sharing that millisecond",
"name": "cursorTag",
"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"
},
"mobile": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminMobileConfig"
},
"web": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminWebConfig"
}
}
},
"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.AdminMobileConfig": {
"type": "object",
"properties": {
"min_app_version": {
"description": "effective floor; empty means no requirement",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminWebConfig": {
"type": "object",
"properties": {
"min_web_version": {
"description": "effective floor; empty means no requirement",
"type": "string"
}
}
},
"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": {
"description": "lifetime count; not reduced by retention",
"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"
},
"scope": {
"description": "matched scope on the first stored packet; null when none was recorded",
"type": "string"
},
"scopeStatus": {
"type": "string",
"enum": [
"matched",
"unscoped",
"unknown",
"unavailable"
]
},
"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.Info": {
"type": "object",
"properties": {
"minAppVersion": {
"description": "MinAppVersion is the oldest allowed app version (X.Y.Z); null means no requirement.",
"type": "string",
"example": "0.1.1"
},
"minWebVersion": {
"description": "MinWebVersion is the oldest allowed Beacon Web version (X.Y.Z); null means no requirement.",
"type": "string",
"example": "2.0.3"
},
"serverVersion": {
"type": "string",
"example": "2.0.2"
}
}
},
"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"
},
"pathKey": {
"description": "stable identity within this IATA; use for route evidence links",
"type": "string"
}
}
},
"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": {
"hour": {
"description": "epoch ms, start of the 1-hour bucket",
"type": "integer"
},
"iata": {
"type": "string"
},
"observationCount": {
"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",
"type": "object"
},
"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"
},
"rawFrom": {
"description": "start of the raw tail, epoch ms",
"type": "integer"
},
"rolledUntil": {
"description": "Hourly only. Buckets before rolledUntil come from rollups and from rawFrom on from raw rows;\nwhen rawFrom is later, the hours between are uncovered, not quiet.",
"type": "integer"
},
"source": {
"description": "raw or hourly; missing records do not prove an outage",
"type": "string"
},
"summary": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivitySummary"
},
"windowEnd": {
"description": "exclusive end, epoch ms; live requests include the current partial bucket",
"type": "integer"
},
"windowStart": {
"description": "inclusive complete-bucket start, epoch ms",
"type": "integer"
}
}
},
"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": {
"description": "stored observations within windowStart/windowEnd",
"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.ObserverDirectory": {
"type": "object",
"properties": {
"coverage": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverDirectoryCoverage"
},
"effectiveSort": {
"type": "string"
},
"generatedAt": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverDirectoryItem"
}
},
"maxObservationCount": {
"description": "Maximum over all matching observers, not only this page; zero when none match.",
"type": "integer"
},
"nextCursor": {
"type": "integer"
},
"observerTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"sort": {
"type": "string"
},
"windowEnd": {
"type": "integer"
},
"windowStart": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverDirectoryCoverage": {
"type": "object",
"properties": {
"completeHours": {
"type": "integer"
},
"expectedHours": {
"type": "integer"
},
"missingHours": {
"type": "integer"
},
"partialHours": {
"type": "integer"
},
"status": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverDirectoryItem": {
"type": "object",
"properties": {
"displayName": {
"description": "friendly name from /status messages",
"type": "string"
},
"iata": {
"description": "most recently heard IATA",
"type": "string"
},
"id": {
"type": "string"
},
"observationCount": {
"description": "Available observations in [windowStart, windowEnd), including zero with missing history.",
"type": "integer"
},
"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.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, or the ACK/TRACE/PING summary; omitted when unavailable",
"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"
},
"maxEntries": {
"description": "longest path received that hour across the requested IATAs; 0 if only empty paths",
"type": "integer"
},
"oneByte": {
"type": "integer"
},
"receptions": {
"type": "integer"
},
"threeByte": {
"type": "integer"
},
"trace": {
"type": "integer"
},
"twoByte": {
"type": "integer"
},
"unclassified": {
"type": "integer"
}
}
},
"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.RouteEvidence": {
"type": "object",
"properties": {
"generatedAt": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
},
"hashSize": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteObservation"
}
},
"matchAvailable": {
"type": "boolean"
},
"matchType": {
"type": "string"
},
"nextPageCursor": {
"type": "string"
},
"pathBytes": {
"type": "string"
},
"route": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute"
},
"windowEnd": {
"type": "integer"
},
"windowStart": {
"type": "integer"
}
}
},
"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.RouteObservation": {
"type": "object",
"properties": {
"heardAt": {
"type": "integer"
},
"id": {
"type": "integer"
},
"observerId": {
"type": "string"
},
"observerName": {
"type": "string"
},
"packetHash": {
"type": "string"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
},
"rssi": {
"type": "integer"
},
"snr": {
"type": "number"
}
}
},
"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.ScopeHour": {
"type": "object",
"properties": {
"hour": {
"description": "epoch ms, start of the UTC hour",
"type": "integer"
},
"nodes": {
"description": "distinct nodes whose adverts were heard in the scope that hour",
"type": "integer"
},
"observers": {
"description": "distinct observers that heard the scope's packets that hour",
"type": "integer"
},
"packets": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats": {
"type": "object",
"properties": {
"hourly": {
"description": "packetCount by hour, oldest first; hours with none omitted",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour"
}
},
"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"
},
"since": {
"description": "epoch ms, start of the window",
"type": "integer"
},
"totalObservations": {
"type": "integer"
},
"totalPackets": {
"description": "distinct per hour (see StatsSeriesValues)",
"type": "integer"
},
"until": {
"description": "epoch ms, exclusive end of the window",
"type": "integer"
},
"windowHours": {
"description": "complete rolled hours the totals cover, at most 24",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeries": {
"type": "object",
"properties": {
"completeHours": {
"description": "hours contributing to summary",
"type": "integer"
},
"earliestComplete": {
"description": "first complete hour held, epoch ms; null if none",
"type": "integer"
},
"hours": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesHour"
}
},
"revision": {
"description": "changes whenever rolled hours, their status or coverage change",
"type": "integer"
},
"since": {
"description": "effective start, epoch ms on a UTC hour",
"type": "integer"
},
"summary": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues"
},
"until": {
"description": "effective exclusive end, epoch ms on a UTC hour",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesHour": {
"type": "object",
"properties": {
"hour": {
"description": "epoch ms, start of the hour",
"type": "integer"
},
"status": {
"description": "partial: raw rows deleted before it was rolled",
"type": "string",
"enum": [
"complete",
"partial",
"missing"
]
},
"values": {
"description": "null unless complete",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues"
}
]
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.StatsSeriesValues": {
"type": "object",
"properties": {
"activeIatas": {
"description": "distinct across the hour or window",
"type": "integer"
},
"activeObservers": {
"description": "distinct across the hour or window",
"type": "integer"
},
"activeScopes": {
"description": "distinct across the hour or window",
"type": "integer"
},
"maxPathEntries": {
"type": "integer"
},
"observations": {
"type": "integer"
},
"rssiSamples": {
"type": "integer"
},
"rssiSum": {
"description": "average = rssiSum / rssiSamples",
"type": "number"
},
"scopedPackets": {
"type": "integer"
},
"snrSamples": {
"type": "integer"
},
"snrSum": {
"description": "average = snrSum / snrSamples",
"type": "number"
},
"uniquePackets": {
"type": "integer"
}
}
},
"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": {
"description": "null once the node row has been deleted",
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
},
"publicKey": {
"description": "hex",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode": {
"type": "object",
"properties": {
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
},
"nodeId": {
"description": "null once the node row has been deleted",
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
},
"observationCount": {
"type": "integer"
},
"publicKey": {
"description": "hex",
"type": "string"
}
}
},
"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"
},
{
"description": "Server info for the BEACON Mobile app",
"name": "Info"
}
]
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "2.0.4",
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