dandri/beacon-server
1
0
Fork 0
mirror of https://github.com/MeshCore-Beacon/beacon-server.git synced 2026-10-16 20:20:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7e01abf5a08156d161257974bb6115189925fbd2
beacon-server/docs/docs.go
T

5510 lines
208 KiB
Go
Raw Blame History

// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
import "github.com/swaggo/swag"
const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"termsOfService": "https://github.com/MeshCore-Beacon/beacon-server",
"contact": {
"name": "MeshCore Beacon",
"url": "https://github.com/MeshCore-Beacon/beacon-server"
},
"license": {
"name": "AGPL-3-or-later"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/admin/accounts": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Includes active and inactive accounts, newest first. These records are not login users.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "List operator accounts",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"post": {
"security": [
{
"AdminKey": []
}
],
"description": "Trims the name; names are case-sensitive and unique among active accounts. No credential or login is created.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Create an operator account",
"parameters": [
{
"description": "Account name (1-128 Unicode characters, no control characters); body at most 4 KiB",
"name": "account",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"413": {
"description": "Request Entity Too Large",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"415": {
"description": "Unsupported Media Type",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/accounts/{id}": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Returns active or inactive account records.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Get an operator account",
"parameters": [
{
"type": "string",
"format": "uuid",
"description": "Account UUID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"delete": {
"security": [
{
"AdminKey": []
}
],
"description": "Soft deactivation preserves the record. Its name may be reused by a new account.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Deactivate an operator account",
"parameters": [
{
"type": "string",
"format": "uuid",
"description": "Account UUID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"204": {
"description": "Deactivated"
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/backup": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Opt-in operator export. Returns only a completed bundle; one export/transfer at a time. Contains secrets. Login sessions, external deployment files and import are outside this endpoint.",
"produces": [
"application/gzip"
],
"tags": [
"Admin"
],
"summary": "Download a private database and saved-config backup",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "file"
},
"headers": {
"Content-Disposition": {
"type": "string",
"description": "attachment; filename=beacon-backup.tar.gz"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"409": {
"description": "Conflict",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"504": {
"description": "Gateway Timeout",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"507": {
"description": "Insufficient Storage",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/admin/config": {
"get": {
"security": [
{
"AdminKey": []
}
],
"description": "Returns current CORS options, auth configuration status and configured broker count. Credential fields and other configuration are excluded. Runtime origin updates are lost on restart.",
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Inspect selected running configuration",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"put": {
"security": [
{
"AdminKey": []
}
],
"description": "Replaces only cors.allowed_origins immediately. Updates are serialized; concurrent valid updates are applied one at a time. Already-running requests may finish with the previous policy. Nothing is persisted; restart reloads saved configuration.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin"
],
"summary": "Update runtime CORS origins",
"parameters": [
{
"description": "1-32 ASCII HTTP(S) origins, at most 512 bytes each; one hostname wildcard is supported, or a sole *. Empty/null lists and unsupported fields are rejected. Body at most 16 KiB.",
"name": "config",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"413": {
"description": "Request Entity Too Large",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"415": {
"description": "Unsupported Media Type",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"/brokers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Brokers"
],
"summary": "List all MQTT brokers and their connection status",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api_handlers.BrokerStatus"
}
}
}
}
}
},
"/channels": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "List channels",
"parameters": [
{
"type": "string",
"description": "Single-byte channel hash (hex)",
"name": "hash",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YOW or YOW,YYZ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination; 0 starts from the beginning",
"name": "cursor",
"in": "query"
},
{
"type": "string",
"description": "Opaque nextPageCursor from a previous response; preserves timestamp ties and precision. Cannot be combined with a positive cursor; cursor=0 is allowed.",
"name": "pageCursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelPage"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/channels/{channelID}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "Get channel detail",
"parameters": [
{
"type": "integer",
"description": "Channel integer ID",
"name": "channelID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Channel"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/channels/{channelID}/messages": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Channels"
],
"summary": "List messages for a channel",
"parameters": [
{
"type": "integer",
"description": "Channel integer ID",
"name": "channelID",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Return messages after this epoch ms",
"name": "since",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "Message ID of last item for pagination (results ordered newest first)",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/iatas": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "List all IATA codes",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/iatas/{iata}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "Get a single IATA code",
"parameters": [
{
"type": "string",
"description": "3-letter IATA code",
"name": "iata",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.IATA"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/iatas/{iata}/border": {
"get": {
"produces": [
"application/json"
],
"tags": [
"IATAs"
],
"summary": "Get an IATA's GeoJSON border, if configured",
"parameters": [
{
"type": "string",
"description": "3-letter IATA code",
"name": "iata",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "GeoJSON Feature (Polygon or MultiPolygon geometry, with bbox)",
"schema": {
"type": "object"
}
},
"204": {
"description": "IATA exists but has no border configured"
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/messages": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "List channel messages",
"parameters": [
{
"type": "integer",
"description": "Filter by channel integer ID (mutually exclusive with channelHash)",
"name": "channelID",
"in": "query"
},
{
"type": "string",
"description": "Filter by channel hash byte hex (mutually exclusive with channelID)",
"name": "channelHash",
"in": "query"
},
{
"type": "integer",
"description": "Return messages after this epoch ms",
"name": "since",
"in": "query"
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated e.g. YVR or YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "Message ID of last item for pagination (results ordered newest first)",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/messages/backfill": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Messages"
],
"summary": "Backfill messages after a given message ID",
"parameters": [
{
"type": "integer",
"description": "Return messages after this ID (use last WS event message ID)",
"name": "afterId",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name",
"name": "scope",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 100); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List nodes",
"parameters": [
{
"type": "integer",
"description": "Node type integer (1=companion, 2=repeater, 3=room_server, 4=sensor)",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "Node type name (companion, repeater, room_server, sensor)",
"name": "typeName",
"in": "query"
},
{
"type": "string",
"description": "Filter by single IATA code (case-insensitive)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Partial case-insensitive name match",
"name": "name",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Exact public key match (hex)",
"name": "pubkey",
"in": "query"
},
{
"type": "string",
"description": "Partial public key match: hex prefix, case-insensitive",
"name": "pubkeyPrefix",
"in": "query"
},
{
"type": "boolean",
"description": "Filter by multibyte path support (true/false); omit for no filter",
"name": "supportsMultibytePaths",
"in": "query"
},
{
"type": "boolean",
"description": "Filter by multibyte trace support (true/false); omit for no filter",
"name": "supportsMultibyteTraces",
"in": "query"
},
{
"type": "boolean",
"description": "Include each node's known neighbor IDs (neighborIds field). Bare ?neighbors or ?neighbors=true enables it; omit/false for none",
"name": "neighbors",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_NodeSummary"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes/{nodeId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "Get node detail",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Node"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes/{nodeId}/neighbors": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List neighbors for a node",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/nodes/{nodeId}/observations": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Nodes"
],
"summary": "List packet observations originating from a node",
"parameters": [
{
"type": "string",
"description": "Node UUID",
"name": "nodeId",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Observation ID of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_PacketObservationSummary"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/observers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "List observers",
"parameters": [
{
"type": "string",
"description": "Filter by single IATA code (case-insensitive)",
"name": "iata",
"in": "query"
},
{
"type": "string",
"description": "Filter by multiple IATA codes, comma-separated e.g. YVR,YYJ",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "string",
"description": "Filter by observer type (e.g. meshcoretomqtt, meshcore-ha)",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "Filter by broker name",
"name": "broker",
"in": "query"
},
{
"type": "string",
"description": "Filter by status (online or offline)",
"name": "status",
"in": "query"
},
{
"type": "string",
"description": "Partial case-insensitive display name match",
"name": "name",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name e.g. %23bc (URL-encoded #bc)",
"name": "scope",
"in": "query"
},
{
"type": "integer",
"description": "last_seen epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_ObserverSummary"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/observers/{observerId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "Get observer detail",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Observer"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/observers/{observerId}/activity": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Observers"
],
"summary": "Get observer heard-activity history",
"parameters": [
{
"type": "string",
"description": "Observer UUID",
"name": "observerId",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Trailing window as a Go duration, max 720h (default 24h); max 48h when interval is under 1h",
"name": "range",
"in": "query"
},
{
"type": "string",
"description": "Bucket size: 5m, 15m, 1h, 6h or 24h (default 15m)",
"name": "interval",
"in": "query"
},
{
"type": "integer",
"description": "Optional exclusive end in epoch milliseconds; aligned down to a complete bucket, at most 30 days old. 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"
}
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/regions/{regionId}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Regions"
],
"summary": "Get a single region",
"parameters": [
{
"type": "integer",
"description": "Region ID",
"name": "regionId",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Region"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "List known routes",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code",
"name": "iata",
"in": "query"
},
{
"type": "integer",
"description": "Filter by exact hop count",
"name": "hopCount",
"in": "query"
},
{
"type": "integer",
"description": "Epoch ms timestamp of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/cross": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search for routes that cross IATA boundaries",
"parameters": [
{
"type": "string",
"description": "Source node hash prefix (hex)",
"name": "fromHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Source IATA code",
"name": "fromIata",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex)",
"name": "toHash",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination IATA code",
"name": "toIata",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/routes/search": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Routes"
],
"summary": "Search known routes by source and destination hash",
"parameters": [
{
"type": "string",
"description": "IATA code to search within",
"name": "iata",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Source node hash prefix (hex)",
"name": "from",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Destination node hash prefix (hex)",
"name": "to",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/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, no future end",
"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": "The unfiltered list includes stored imported names after an importer is disabled or a source is removed. Those historical identities are retained indefinitely; listing them does not establish observed traffic or current source membership.",
"produces": [
"application/json"
],
"tags": [
"Scopes"
],
"summary": "List transport scopes",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/scopes/{name}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Scopes"
],
"summary": "Get scope detail by name",
"parameters": [
{
"type": "string",
"description": "Scope name e.g. %23bc (URL-encoded #bc)",
"name": "name",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/clock-drift": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Repeaters/room servers whose clock has drifted beyond the configured threshold, worst first",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/node-types": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Node type breakdown",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeTypeCount"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/observations": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Hourly observation time series",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default 7 days ago)",
"name": "since",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObservationPoint"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/observer-comparison": {
"get": {
"description": "Counts distinct retained packet hashes with route type 0 or 1, using reception time in [since, until). onlyA, onlyB and both partition totalPackets (the union). Repeated receptions count once. These are reported receptions, not a measure of radio packet loss or continuous observer coverage.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Compare flood packets reported by two observers",
"parameters": [
{
"type": "string",
"description": "First observer UUID",
"name": "observerA",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Second, distinct observer UUID",
"name": "observerB",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; later than since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverComparison"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/overview": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Network overview stats (last 24h)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.StatsOverview"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/paths": {
"get": {
"description": "Counts stored receptions in [since, until), at most 30 days. Hash widths count only validated nonempty ordinary header paths (1/2/3 bytes). Empty paths do not vote for a width. TRACE header paths contain signal readings and are separate. Missing payload type or inconsistent/unsupported path metadata is unclassified. The four categories partition total receptions. Flood paths accumulate entries; direct paths contain remaining entries, so counts do not measure distance or a complete traversed route. Both boundaries round down to UTC hours and the response reports that effective window. Reads use materialized snapshots refreshed by background.view_refresh; the current partial hour is excluded and missing hours are omitted.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Received path-entry and hash-width distributions",
"parameters": [
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; at most 30 days after since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/payload-breakdown": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Observation counts by payload type (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/radio-presets": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Radio preset usage by IATA",
"parameters": [
{
"type": "string",
"description": "Filter by preset string e.g. 910.525,62.5,7",
"name": "preset",
"in": "query"
},
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/scopes": {
"get": {
"description": "Counts each packet, observer and node once per scope. IATA filters use retained observations for packets/observers and node IATA memberships for nodes. Without filters, returns global totals. Scopes with zero matching counts remain listed; an empty region returns an empty array.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Scope statistics",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Single IATA code; used when iatas is absent",
"name": "iata",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs; combined with explicit IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/signal": {
"get": {
"description": "Aggregates stored observer receptions in [since, until), at most 30 days. SNR is dB; RSSI is dBm. Null/non-finite readings and the zero/zero unavailable sentinel are excluded per metric; actual zero SNR with nonzero RSSI remains valid. Averages are null without samples. Histogram bounds are lower-inclusive/upper-exclusive, with null for unbounded ends. Both boundaries round down to UTC hours and the response reports that effective window. Reads use hourly materialized snapshots refreshed by background.view_refresh; the current partial hour is excluded and absent hours are omitted. These last-hop readings do not measure end-to-end quality or packet loss.",
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Reception signal distributions and hourly trends",
"parameters": [
{
"type": "integer",
"description": "Inclusive start, epoch milliseconds (0 through 253402300799999)",
"name": "since",
"in": "query",
"required": true
},
{
"type": "integer",
"description": "Exclusive end, epoch milliseconds; at most 30 days after since",
"name": "until",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Comma-separated reception IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Region slug, expands to member IATAs",
"name": "region",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalStats"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-advertisers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N nodes by distinct ADVERT packet count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-nodes": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N nodes by observation count (from materialized view)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-observers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N observers by observation count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/stats/top-talkers": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Stats"
],
"summary": "Top N companion names by decrypted channel message count (last 24h by default)",
"parameters": [
{
"type": "string",
"description": "Comma-separated IATA codes",
"name": "iatas",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID, expands to member IATAs",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug, expands to member IATAs",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Start of window epoch ms (default last 24h)",
"name": "since",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 10); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/traces": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Traces"
],
"summary": "List trace tags",
"parameters": [
{
"type": "string",
"description": "Filter by IATA code(s), comma-separated",
"name": "iatas",
"in": "query"
},
{
"type": "string",
"description": "Filter by region slug",
"name": "region",
"in": "query"
},
{
"type": "integer",
"description": "Filter by region ID",
"name": "regionId",
"in": "query"
},
{
"type": "string",
"description": "Filter by transport scope name",
"name": "scope",
"in": "query"
},
{
"type": "string",
"description": "Filter by type: TRACE or PING (default: all)",
"name": "type",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003e= since (epoch ms)",
"name": "since",
"in": "query"
},
{
"type": "integer",
"description": "Filter by first_heard_at \u003c= until (epoch ms)",
"name": "until",
"in": "query"
},
{
"type": "integer",
"description": "last_heard_at epoch ms of last item for pagination",
"name": "cursor",
"in": "query"
},
{
"maximum": 200,
"minimum": 1,
"type": "integer",
"description": "Max results (default 50); must be positive, values above 200 are clamped",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
},
"/traces/{tag}": {
"get": {
"produces": [
"application/json"
],
"tags": [
"Traces"
],
"summary": "Get full trace detail by tag",
"parameters": [
{
"type": "string",
"description": "Trace tag hex e.g. a3f1b2c4",
"name": "tag",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceDetail"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/internal_api_handlers.APIError"
}
}
}
}
}
},
"definitions": {
"github_com_MeshCore-Beacon_beacon-server_internal_api.Account": {
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"deactivated_at": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AccountList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.Account"
}
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminAuthConfig": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminCORSConfig": {
"type": "object",
"properties": {
"allow_credentials": {
"type": "boolean"
},
"allowed_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"allowed_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"allowed_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"max_age": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig": {
"type": "object",
"properties": {
"auth": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminAuthConfig"
},
"cors": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminCORSConfig"
},
"ingest": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminIngestConfig"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdminIngestConfig": {
"type": "object",
"properties": {
"broker_count": {
"description": "BrokerCount counts configured broker workers, not active MQTT connections\nor a configurable processing-worker pool.",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation": {
"type": "object",
"properties": {
"heardAt": {
"description": "epoch ms",
"type": "integer"
},
"hopCount": {
"type": "integer"
},
"iata": {
"type": "string"
},
"id": {
"description": "observation ID, use as cursor for pagination",
"type": "integer"
},
"nodeName": {
"type": "string"
},
"nodePublicKey": {
"description": "hex-encoded",
"type": "string"
},
"packetHash": {
"description": "hex-encoded",
"type": "string"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
},
"rssi": {
"type": "integer"
},
"snr": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Channel": {
"type": "object",
"properties": {
"channelHash": {
"description": "hex-encoded single-byte hash",
"type": "string"
},
"hashtag": {
"description": "tag name without # prefix; non-nil only for hashtag channels",
"type": "string"
},
"id": {
"type": "integer"
},
"isHashtag": {
"description": "true if key was derived from a hashtag PSK",
"type": "boolean"
},
"keyFingerprint": {
"description": "first 8 bytes of SHA256(key), hex-encoded",
"type": "string"
},
"keyKnown": {
"description": "true if Beacon has a decryption key for this channel",
"type": "boolean"
},
"lastSeen": {
"description": "epoch ms, time of most recent message",
"type": "integer"
},
"messageCount": {
"type": "integer"
},
"name": {
"description": "display name from config or nil",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelMessage": {
"type": "object",
"properties": {
"channelHash": {
"description": "hex-encoded single-byte channel hash",
"type": "string"
},
"content": {
"description": "decrypted message text",
"type": "string"
},
"id": {
"type": "integer"
},
"observationCount": {
"description": "number of packet_observations rows for this message's packet hash",
"type": "integer"
},
"packetHash": {
"description": "hex-encoded packet hash for correlation with packet events",
"type": "string"
},
"senderName": {
"description": "display name from the decrypted payload",
"type": "string"
},
"sentAt": {
"description": "epoch ms, from the sender's embedded timestamp",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelPage": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary"
}
},
"nextCursor": {
"type": "integer"
},
"nextPageCursor": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary": {
"type": "object",
"properties": {
"channelHash": {
"description": "hex-encoded single-byte hash",
"type": "string"
},
"id": {
"type": "integer"
},
"isHashtag": {
"description": "true if key was derived from a hashtag PSK",
"type": "boolean"
},
"keyKnown": {
"description": "true if Beacon has a decryption key for this channel",
"type": "boolean"
},
"lastSeen": {
"description": "epoch ms, time of most recent message",
"type": "integer"
},
"name": {
"description": "display name from config or nil",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ClockDriftEntry": {
"type": "object",
"properties": {
"clockCheckedAt": {
"description": "epoch ms",
"type": "integer"
},
"clockDriftSeconds": {
"description": "signed; +ve = device ahead of server",
"type": "integer"
},
"iatas": {
"description": "IATAs this node has been heard in",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA"
}
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CreateAccountRequest": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop": {
"type": "object",
"properties": {
"fromIata": {
"type": "string"
},
"fromNode": {
"description": "last node in source IATA",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
]
},
"lastSeen": {
"description": "epoch ms",
"type": "integer"
},
"toIata": {
"type": "string"
},
"toNode": {
"description": "first node in target IATA",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
]
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute": {
"type": "object",
"properties": {
"crossHop": {
"description": "the boundary hop",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop"
}
]
},
"sourceSegment": {
"description": "route segment in source IATA",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"targetSegment": {
"description": "route segment in target IATA",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"totalHops": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.IATA": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"lat": {
"type": "number"
},
"lon": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute": {
"type": "object",
"properties": {
"firstSeen": {
"description": "epoch ms",
"type": "integer"
},
"hopCount": {
"type": "integer"
},
"hops": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop"
}
},
"iata": {
"type": "string"
},
"id": {
"type": "integer"
},
"lastSeen": {
"description": "epoch ms",
"type": "integer"
},
"observationCount": {
"type": "integer"
},
"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": {
"activeObservers": {
"type": "integer"
},
"hour": {
"description": "epoch ms, start of the 1-hour bucket",
"type": "integer"
},
"iata": {
"type": "string"
},
"observationCount": {
"type": "integer"
},
"uniquePackets": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Observer": {
"type": "object",
"properties": {
"batteryLevel": {
"description": "volts, nil if mains powered",
"type": "number"
},
"brokers": {
"description": "broker names this observer has been seen on",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverBroker"
}
},
"displayName": {
"description": "friendly name from /status messages",
"type": "string"
},
"firmwareBuild": {
"type": "string"
},
"firmwareVersion": {
"type": "string"
},
"firstSeen": {
"description": "epoch ms",
"type": "integer"
},
"hardwareModel": {
"type": "string"
},
"iata": {
"description": "most recently heard IATA",
"type": "string"
},
"id": {
"type": "string"
},
"lastSeen": {
"description": "epoch ms",
"type": "integer"
},
"lastStatusAt": {
"description": "epoch ms",
"type": "integer"
},
"observationCount": {
"description": "legacy cumulative presence counter; includes non-packet events",
"type": "integer"
},
"observerType": {
"description": "e.g. \"meshcoretomqtt\", \"meshcoreha\"",
"type": "string"
},
"publicKey": {
"description": "hex-encoded public key",
"type": "string"
},
"radio": {
"description": "friendly radio param string: freqMhz,BwKhz,SF e.g. \"910.525,62.5,7\"",
"type": "string"
},
"radioBwKhz": {
"description": "bandwidth in kHz",
"type": "number"
},
"radioCr": {
"description": "coding rate denominator",
"type": "integer"
},
"radioFreqMhz": {
"description": "MHz e.g. 910.525",
"type": "number"
},
"radioSf": {
"description": "LoRa spreading factor",
"type": "integer"
},
"scopes": {
"description": "list of observer forwarded scopes matched to config",
"type": "array",
"items": {
"type": "string"
}
},
"softwareVersion": {
"type": "string"
},
"status": {
"description": "\"online\" or \"offline\" derived from last_status_at",
"type": "string"
},
"statusMetadata": {
"description": "raw /status JSON payload"
},
"uptimeSeconds": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivity": {
"type": "object",
"properties": {
"generatedAt": {
"description": "response computation time, not proof of continuous coverage",
"type": "integer"
},
"interval": {
"type": "string"
},
"payloadTypes": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem"
}
},
"points": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityPoint"
}
},
"radio": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivityRadio"
},
"range": {
"type": "string"
},
"source": {
"description": "raw or hourly; missing records do not prove an outage",
"type": "string"
},
"summary": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverActivitySummary"
},
"windowEnd": {
"description": "exclusive 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.ObserverSummary": {
"type": "object",
"properties": {
"displayName": {
"description": "friendly name from /status messages",
"type": "string"
},
"iata": {
"description": "most recently heard IATA",
"type": "string"
},
"id": {
"type": "string"
},
"observerType": {
"description": "e.g. \"meshcoretomqtt\", \"meshcoreha\"",
"type": "string"
},
"radio": {
"description": "friendly radio param string: freqMhz,BwKhz,SF e.g. \"910.525,62.5,7\"",
"type": "string"
},
"scopes": {
"description": "list of observer forwarded scopes matched to config",
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"description": "\"online\" or \"offline\" derived from last_status_at",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetry": {
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"points": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint"
}
},
"range": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint": {
"type": "object",
"properties": {
"airtimeRxSecs": {
"type": "number"
},
"airtimeTxSecs": {
"type": "number"
},
"batteryMv": {
"type": "integer"
},
"noiseFloorDb": {
"type": "number"
},
"queueLength": {
"type": "integer"
},
"receiveErrors": {
"type": "integer"
},
"t": {
"description": "epoch ms",
"type": "integer"
},
"uptimeSeconds": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Packet": {
"type": "object",
"properties": {
"channelHash": {
"description": "hex-encoded single byte; non-nil for group_text/group_data",
"type": "string"
},
"decrypted": {
"description": "true if group text was successfully decrypted",
"type": "boolean"
},
"firstHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"firstToLastMs": {
"description": "ms between first and last observation",
"type": "integer"
},
"header": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketHeader"
},
"lastHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"observationCount": {
"type": "integer"
},
"observations": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail"
}
},
"originPubkey": {
"description": "hex-encoded; nil when not extractable from payload",
"type": "string"
},
"packetHash": {
"type": "string"
},
"parsedPayload": {
"type": "array",
"items": {
"type": "integer"
}
},
"rawPayload": {
"description": "hex-encoded payload bytes (excludes header and path)",
"type": "string"
},
"resolvedRoute": {
"description": "trace packets only: resolved intended route",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"scope": {
"description": "matched transport scope name e.g. \"#bc\"",
"type": "string"
},
"transportCodes": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketHeader": {
"type": "object",
"properties": {
"payloadType": {
"description": "bits 2-5",
"type": "integer"
},
"payloadTypeName": {
"description": "advert, request, group_text, etc.",
"type": "string"
},
"payloadVersion": {
"description": "bits 6-7",
"type": "integer"
},
"raw": {
"description": "hex-encoded single byte",
"type": "string"
},
"routeType": {
"description": "bits 0-1",
"type": "integer"
},
"routeTypeName": {
"description": "FLOOD, DIRECT, TRANSPORT_FLOOD, TRANSPORT_DIRECT",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketLatestObserver": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"id": {
"type": "string"
},
"pathBytes": {
"description": "hex-encoded accumulated path hashes",
"type": "string"
},
"pathLength": {
"description": "PathLength/PathBytes and captured endpoint resolutions are stored on the observation,\nso list/backfill reads need no per-hash resolution queries. Legacy observations have\nno endpoint snapshot. ResolvedPath remains a detail/opted-in WS feature.",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength"
}
]
},
"resolvedDestination": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
},
"resolvedPath": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"resolvedSource": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationDetail": {
"type": "object",
"properties": {
"heardAt": {
"description": "epoch ms",
"type": "integer"
},
"iata": {
"type": "string"
},
"id": {
"type": "integer"
},
"observerId": {
"type": "string"
},
"observerName": {
"type": "string"
},
"pathBytes": {
"description": "hex-encoded accumulated path hashes",
"type": "string"
},
"pathLength": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength"
},
"propagationTimeMs": {
"description": "ms since first observation; 0 for first",
"type": "integer"
},
"radio": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketRadio"
},
"resolvedDestination": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
},
"resolvedPath": {
"description": "per-observation resolved path hashes",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"resolvedSource": {
"description": "ResolvedSource/ResolvedDestination are the packet's endpoints, when the payload type\ncarries one. Prefer the snapshot captured at ingest; legacy observations without a\nsnapshot use the current node registry. Endpoint matching itself is unchanged:\nan exact match for ADVERT's full pubkey, an ambiguous\nhash-prefix match (like intermediate hops) for TEXT_MESSAGE/PATH/ANON_REQ's 1-byte\nsource/destination hashes. Nil when the payload type doesn't carry one at all (e.g.\nGRP_TXT/GRP_DATA/TRACE aren't node-to-node addressed) -- see BuildResolvedPath and\nResolveExactNode for how each is built.",
"allOf": [
{
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
]
},
"rssi": {
"type": "integer"
},
"snr": {
"type": "number"
},
"sourceBroker": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary": {
"type": "object",
"properties": {
"heardAt": {
"description": "epoch ms",
"type": "integer"
},
"hopCount": {
"type": "integer"
},
"iata": {
"type": "string"
},
"id": {
"description": "observation ID, use as cursor for pagination",
"type": "integer"
},
"packetHash": {
"description": "hex-encoded",
"type": "string"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
},
"rssi": {
"type": "integer"
},
"snr": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketPathLength": {
"type": "object",
"properties": {
"hashSize": {
"description": "per-hop hash size in bytes (1, 2, or 3)",
"type": "integer"
},
"hopCount": {
"description": "number of path hashes present",
"type": "integer"
},
"raw": {
"description": "hex-encoded single byte",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketRadio": {
"type": "object",
"properties": {
"bandwidthKhz": {
"type": "number"
},
"codingRate": {
"type": "integer"
},
"freqMhz": {
"type": "number"
},
"spreadFactor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketSummary": {
"type": "object",
"properties": {
"firstHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"lastHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"latestObserver": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketLatestObserver"
},
"observationCount": {
"type": "integer"
},
"packetHash": {
"description": "hex-encoded",
"type": "string"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
},
"routeType": {
"type": "integer"
},
"routeTypeName": {
"type": "string"
},
"scope": {
"description": "matched transport scope name e.g. \"#bc\"",
"type": "string"
},
"summary": {
"description": "advert name from this packet; omitted when unavailable or unsupported",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PacketTransportCodes": {
"type": "object",
"properties": {
"regionCode": {
"type": "integer"
},
"subRegionCode": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_AdvertObservation": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdvertObservation"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_NodeSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_ObserverSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Page-github_com_MeshCore-Beacon_beacon-server_internal_api_PacketObservationSummary": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PacketObservationSummary"
}
},
"nextCursor": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth": {
"type": "object",
"properties": {
"bytes": {
"type": "integer"
},
"receptions": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour": {
"type": "object",
"properties": {
"empty": {
"type": "integer"
},
"hour": {
"type": "integer"
},
"oneByte": {
"type": "integer"
},
"receptions": {
"type": "integer"
},
"threeByte": {
"type": "integer"
},
"trace": {
"type": "integer"
},
"twoByte": {
"type": "integer"
},
"unclassified": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin": {
"type": "object",
"properties": {
"entries": {
"type": "integer"
},
"receptions": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats": {
"type": "object",
"properties": {
"empty": {
"type": "integer"
},
"hashWidths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth"
}
},
"hashed": {
"type": "integer"
},
"hourly": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour"
}
},
"pathLengths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin"
}
},
"receptions": {
"type": "integer"
},
"since": {
"type": "integer"
},
"trace": {
"type": "integer"
},
"unclassified": {
"type": "integer"
},
"until": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"payloadType": {
"type": "integer"
},
"payloadTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset": {
"type": "object",
"properties": {
"count": {
"description": "number of observers or nodes on this preset in this IATA",
"type": "integer"
},
"iata": {
"type": "string"
},
"preset": {
"description": "\"freqMhz,bwKhz,sf\" e.g. \"910.525,62.5,7\"",
"type": "string"
},
"sourceType": {
"description": "\"observer\" or \"node\"",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop": {
"type": "object",
"properties": {
"hash": {
"description": "hex-encoded path hash",
"type": "string"
},
"snr": {
"description": "signal-to-noise ratio in dB, if available",
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.Region": {
"type": "object",
"properties": {
"centerLat": {
"description": "map center latitude",
"type": "number"
},
"centerLng": {
"description": "map center longitude",
"type": "number"
},
"description": {
"type": "string"
},
"iatas": {
"description": "member IATA codes",
"type": "array",
"items": {
"type": "string"
}
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"slug": {
"description": "URL-safe identifier e.g. \"western-canada\"",
"type": "string"
},
"zoomLevel": {
"description": "suggested map zoom level",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"slug": {
"description": "URL-safe identifier e.g. \"western-canada\"",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop": {
"type": "object",
"properties": {
"confidence": {
"description": "\"high\", \"ambiguous\", or \"none\"",
"type": "string"
},
"nodes": {
"description": "empty for \"none\", one for \"high\", multiple for \"ambiguous\"",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode"
}
},
"snr": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"name": {
"type": "string"
},
"publicKey": {
"description": "hex-encoded prefix used for resolution",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.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"
},
"nextCursor": {
"type": "integer"
},
"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.ScopeStats": {
"type": "object",
"properties": {
"name": {
"description": "normalized scope name e.g. \"#bc\"",
"type": "string"
},
"nodeCount": {
"description": "distinct nodes with this as their default scope",
"type": "integer"
},
"observerCount": {
"description": "distinct observers that forwarded packets in this scope",
"type": "integer"
},
"packetCount": {
"description": "distinct packets matched to this scope",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"lower": {
"type": "number"
},
"upper": {
"type": "number"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour": {
"type": "object",
"properties": {
"hour": {
"type": "integer"
},
"receptions": {
"type": "integer"
},
"rssiAverage": {
"type": "number"
},
"rssiSamples": {
"type": "integer"
},
"snrAverage": {
"type": "number"
},
"snrSamples": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric": {
"type": "object",
"properties": {
"average": {
"type": "number"
},
"histogram": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalBin"
}
},
"samples": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.SignalStats": {
"type": "object",
"properties": {
"hourly": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalHour"
}
},
"receptions": {
"type": "integer"
},
"rssi": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric"
},
"since": {
"type": "integer"
},
"snr": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.SignalMetric"
},
"until": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.StatsOverview": {
"type": "object",
"properties": {
"activeIatas": {
"type": "integer"
},
"activeObservers": {
"type": "integer"
},
"totalObservations": {
"type": "integer"
},
"totalPackets": {
"type": "integer"
},
"windowHours": {
"description": "always 24 for now",
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopAdvertiser": {
"type": "object",
"properties": {
"advertCount": {
"type": "integer"
},
"directAdvertCount": {
"type": "integer"
},
"floodAdvertCount": {
"description": "FloodAdvertCount/DirectAdvertCount split AdvertCount by how the advert was routed:\nflood = route type 0 (transport_flood) or 1 (flood), broadcast with no known path;\ndirect = route type 2 (direct) or 3 (transport_direct), routed along a known path.\nFloodAdvertCount + DirectAdvertCount == AdvertCount.",
"type": "integer"
},
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopNode": {
"type": "object",
"properties": {
"iata": {
"type": "string"
},
"lastHeard": {
"description": "epoch ms",
"type": "integer"
},
"nodeId": {
"type": "string"
},
"nodeName": {
"type": "string"
},
"nodeType": {
"type": "integer"
},
"nodeTypeName": {
"type": "string"
},
"observationCount": {
"type": "integer"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopObserver": {
"type": "object",
"properties": {
"displayName": {
"type": "string"
},
"iata": {
"type": "string"
},
"observationCount": {
"type": "integer"
},
"observerId": {
"type": "string"
},
"observerType": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TopTalker": {
"type": "object",
"properties": {
"lastSent": {
"description": "epoch ms",
"type": "integer"
},
"messageCount": {
"type": "integer"
},
"senderName": {
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TraceDetail": {
"type": "object",
"properties": {
"packets": {
"description": "all packets observed for this trace",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket"
}
},
"traceTag": {
"description": "hex-encoded 4-byte tag",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TracePacket": {
"type": "object",
"properties": {
"firstHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"lastHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"packetHash": {
"description": "hex-encoded packet hash",
"type": "string"
},
"rawPath": {
"description": "hops as received in the packet",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop"
}
},
"resolvedRoute": {
"description": "hops resolved to known nodes",
"type": "array",
"items": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop"
}
},
"routeType": {
"description": "numeric route type",
"type": "integer"
},
"routeTypeName": {
"description": "human-readable route type",
"type": "string"
},
"scope": {
"description": "transport scope name, if known",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary": {
"type": "object",
"properties": {
"firstHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"iataCount": {
"description": "number of distinct IATAs where heard",
"type": "integer"
},
"lastHeardAt": {
"description": "epoch ms",
"type": "integer"
},
"packetCount": {
"description": "number of packets with this trace tag",
"type": "integer"
},
"pathHashes": {
"description": "hops from the most complete observation",
"type": "array",
"items": {
"type": "string"
}
},
"snrValues": {
"description": "SNR per hop from the most complete observation",
"type": "array",
"items": {
"type": "number"
}
},
"traceTag": {
"description": "hex-encoded 4-byte tag",
"type": "string"
},
"traceType": {
"description": "TRACE or PING",
"type": "string"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest": {
"type": "object",
"required": [
"allowed_origins"
],
"properties": {
"allowed_origins": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigRequest": {
"type": "object",
"required": [
"cors"
],
"properties": {
"cors": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminCORSRequest"
}
}
},
"github_com_MeshCore-Beacon_beacon-server_internal_api.UpdateAdminConfigResponse": {
"type": "object",
"properties": {
"config": {
"$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.AdminConfig"
},
"persisted": {
"type": "boolean"
},
"requires_restart": {
"type": "boolean"
}
}
},
"internal_api_handlers.APIError": {
"type": "object",
"properties": {
"code": {
"description": "e.g. \"not_found\", \"bad_request\"",
"type": "string"
},
"message": {
"description": "e.g. \"channel not found\"",
"type": "string"
}
}
},
"internal_api_handlers.BrokerStatus": {
"type": "object",
"properties": {
"connected": {
"type": "boolean"
},
"name": {
"type": "string"
}
}
}
},
"securityDefinitions": {
"AdminKey": {
"description": "Enter Bearer followed by the configured operator key. Use HTTPS.",
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"tags": [
{
"description": "Airport/location codes that group observers and packets",
"name": "IATAs"
},
{
"description": "Super-regions grouping multiple IATAs",
"name": "Regions"
},
{
"description": "MeshCore MQTT observers (gateways)",
"name": "Observers"
},
{
"description": "MeshCore radio nodes",
"name": "Nodes"
},
{
"description": "LoRa packets heard by observers",
"name": "Packets"
},
{
"description": "MeshCore group text channels",
"name": "Channels"
},
{
"description": "Decrypted channel messages",
"name": "Messages"
},
{
"description": "MQTT broker connection status",
"name": "Brokers"
},
{
"description": "Network statistics and time series",
"name": "Stats"
}
]
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "1.6.0",
Host: "localhost:8080",
BasePath: "/api/v1",
Schemes: []string{"http", "https"},
Title: "MeshCore Beacon API",
Description: "MeshCore network observation backend. Ingests LoRa packets from MQTT brokers, stores in PostgreSQL, and streams live events via WebSocket.\nREST requests share a configurable per-client rate limit (default 300/minute and a 300-request one-second burst cap). Exceeded limits return HTTP 429 with error.code=rate_limited and a Retry-After header in seconds. CORS preflights and WebSocket upgrades do not consume this API budget.\nWebSocket upgrade attempts at /ws have a configurable per-client limit (default 10/minute, including failed handshakes). Rate exhaustion returns HTTP 429 with Retry-After before upgrade. An accepted socket exceeding the concurrent cap closes with code 1013 before hello; established connections remain open.",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
RightDelim: "}}",
}
func init() {
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
Reference in New Issue View Git Blame Copy Permalink