{ "schemes": [ "http", "https" ], "swagger": "2.0", "info": { "description": "MeshCore network observation backend. Ingests LoRa packets from MQTT brokers, stores in PostgreSQL, and streams live events via WebSocket.", "title": "MeshCore Beacon API", "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": "1.5.4" }, "host": "localhost:8080", "basePath": "/api/v1", "paths": { "/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", "name": "cursor", "in": "query" }, { "type": "integer", "description": "Max results (default 50)", "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_ChannelSummary" } }, "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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 100)", "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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 50)", "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}/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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 50)", "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" }, { "type": "integer", "description": "Max results (default 100)", "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" }, { "type": "integer", "description": "Max results (default 50)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } } } } }, "/routes/cross": { "get": { "produces": [ "application/json" ], "tags": [ "Routes" ], "summary": "Search for routes that cross IATA boundaries", "parameters": [ { "type": "string", "description": "Source node hash prefix (hex)", "name": "fromHash", "in": "query", "required": true }, { "type": "string", "description": "Source IATA code", "name": "fromIata", "in": "query", "required": true }, { "type": "string", "description": "Destination node hash prefix (hex)", "name": "toHash", "in": "query", "required": true }, { "type": "string", "description": "Destination IATA code", "name": "toIata", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } } } } }, "/routes/search": { "get": { "produces": [ "application/json" ], "tags": [ "Routes" ], "summary": "Search known routes by source and destination hash", "parameters": [ { "type": "string", "description": "IATA code to search within", "name": "iata", "in": "query", "required": true }, { "type": "string", "description": "Source node hash prefix (hex)", "name": "from", "in": "query", "required": true }, { "type": "string", "description": "Destination node hash prefix (hex)", "name": "to", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } } } } }, "/scopes": { "get": { "produces": [ "application/json" ], "tags": [ "Scopes" ], "summary": "List transport scopes", "parameters": [ { "type": "string", "description": "Filter by IATA code(s), comma-separated", "name": "iatas", "in": "query" }, { "type": "string", "description": "Filter by region slug", "name": "region", "in": "query" }, { "type": "integer", "description": "Filter by region ID", "name": "regionId", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } } } } }, "/scopes/{name}": { "get": { "produces": [ "application/json" ], "tags": [ "Scopes" ], "summary": "Get scope detail by name", "parameters": [ { "type": "string", "description": "Scope name e.g. %23bc (URL-encoded #bc)", "name": "name", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/internal_api_handlers.APIError" } } } } }, "/stats/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/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/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": { "produces": [ "application/json" ], "tags": [ "Stats" ], "summary": "Scope statistics", "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats" } } }, "500": { "description": "Internal Server Error", "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" }, { "type": "integer", "description": "Max results (default 10)", "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" }, { "type": "integer", "description": "Max results (default 10)", "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" }, { "type": "integer", "description": "Max results (default 10)", "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" }, { "type": "integer", "description": "Max results (default 10)", "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" }, { "type": "integer", "description": "Max results (default 50)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.TraceTagSummary" } } }, "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.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.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.CrossIATAHop": { "type": "object", "properties": { "fromIata": { "type": "string" }, "fromNode": { "description": "last node in source IATA", "allOf": [ { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode" } ] }, "lastSeen": { "description": "epoch ms", "type": "integer" }, "toIata": { "type": "string" }, "toNode": { "description": "first node in target IATA", "allOf": [ { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode" } ] } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATARoute": { "type": "object", "properties": { "crossHop": { "description": "the boundary hop", "allOf": [ { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.CrossIATAHop" } ] }, "sourceSegment": { "description": "route segment in source IATA", "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop" } }, "targetSegment": { "description": "route segment in target IATA", "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop" } }, "totalHops": { "type": "integer" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.IATA": { "type": "object", "properties": { "displayName": { "type": "string" }, "iata": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.KnownRoute": { "type": "object", "properties": { "firstSeen": { "description": "epoch ms", "type": "integer" }, "hopCount": { "type": "integer" }, "hops": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop" } }, "iata": { "type": "string" }, "id": { "type": "integer" }, "lastSeen": { "description": "epoch ms", "type": "integer" }, "observationCount": { "type": "integer" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.Node": { "type": "object", "properties": { "clockCheckedAt": { "type": "integer" }, "clockDriftSeconds": { "description": "Clock drift, repeaters/room servers only (nodeType 2/3); omitted entirely for other\nnode types or when no qualifying advert has been measured yet. Device minus server\ntime, in seconds, from the advert's self-reported timestamp: +ve = device ahead.\nclockCheckedAt is the server receive time of the advert this was measured from (same\nmoment as lastAdvertAt). clockOutOfSync is |clockDriftSeconds| exceeding a configured\nthreshold (default 5m) -- see internal/config.ResolvedConfig.ClockDriftThreshold.", "type": "integer" }, "clockOutOfSync": { "type": "boolean" }, "defaultScope": { "description": "most recently matched transport scope name e.g. \"#bc\"", "type": "string" }, "firstSeen": { "description": "epoch ms", "type": "integer" }, "iatas": { "description": "IATAs where this node has been heard, with last heard timestamps", "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeIATA" } }, "id": { "type": "string" }, "isObserver": { "description": "true if this node is also a known observer", "type": "boolean" }, "knownNeighborCount": { "type": "integer" }, "lastAdvertAt": { "description": "epoch ms, nil if no advert received", "type": "integer" }, "lastSeen": { "description": "epoch ms", "type": "integer" }, "lat": { "description": "decimal degrees, from advert AppData", "type": "number" }, "lng": { "description": "decimal degrees, from advert AppData", "type": "number" }, "locationSource": { "description": "\"advert\" or \"manual\"", "type": "string" }, "metadata": { "description": "raw JSONB metadata" }, "minFirmwareVersion": { "description": "derived from capability flags", "type": "string" }, "name": { "type": "string" }, "neighborIds": { "description": "only populated when the list request opts in; see ?neighbors=true", "type": "array", "items": { "type": "string" } }, "neighbors": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.NodeNeighbor" } }, "nodeType": { "description": "1=companion, 2=repeater, 3=room_server, 4=sensor", "type": "integer" }, "nodeTypeName": { "type": "string" }, "observerId": { "description": "UUID of the associated observer row, if any", "type": "string" }, "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" }, "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": { "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.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.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": { "airtimeRxPct": { "type": "number" }, "airtimeTxPct": { "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" } } }, "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 a resolvable one: an 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": "human-readable payload summary", "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_ChannelSummary": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ChannelSummary" } }, "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.PayloadBreakdownItem": { "type": "object", "properties": { "count": { "type": "integer" }, "payloadType": { "type": "integer" }, "payloadTypeName": { "type": "string" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.RadioPreset": { "type": "object", "properties": { "count": { "description": "number of observers or nodes on this preset in this IATA", "type": "integer" }, "iata": { "type": "string" }, "preset": { "description": "\"freqMhz,bwKhz,sf\" e.g. \"910.525,62.5,7\"", "type": "string" }, "sourceType": { "description": "\"observer\" or \"node\"", "type": "string" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.RawHop": { "type": "object", "properties": { "hash": { "description": "hex-encoded path hash", "type": "string" }, "snr": { "description": "signal-to-noise ratio in dB, if available", "type": "number" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.Region": { "type": "object", "properties": { "centerLat": { "description": "map center latitude", "type": "number" }, "centerLng": { "description": "map center longitude", "type": "number" }, "description": { "type": "string" }, "iatas": { "description": "member IATA codes", "type": "array", "items": { "type": "string" } }, "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "description": "URL-safe identifier e.g. \"western-canada\"", "type": "string" }, "zoomLevel": { "description": "suggested map zoom level", "type": "integer" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.RegionSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "description": "URL-safe identifier e.g. \"western-canada\"", "type": "string" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedHop": { "type": "object", "properties": { "confidence": { "description": "\"high\", \"ambiguous\", or \"none\"", "type": "string" }, "nodes": { "description": "empty for \"none\", one for \"high\", multiple for \"ambiguous\"", "type": "array", "items": { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode" } }, "snr": { "type": "number" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode": { "type": "object", "properties": { "id": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "publicKey": { "description": "hex-encoded prefix used for resolution", "type": "string" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.RouteHop": { "type": "object", "properties": { "hashBytes": { "description": "hex-encoded hash prefix", "type": "string" }, "node": { "description": "populated when node details are available", "allOf": [ { "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ResolvedNode" } ] }, "nodeId": { "type": "string" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeDetail": { "type": "object", "properties": { "iataCount": { "type": "integer" }, "iatas": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "nodeCount": { "type": "integer" }, "observerCount": { "type": "integer" }, "packetCount": { "type": "integer" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats": { "type": "object", "properties": { "name": { "description": "normalized scope name e.g. \"#bc\"", "type": "string" }, "nodeCount": { "description": "distinct nodes with this as their default scope", "type": "integer" }, "observerCount": { "description": "distinct observers that forwarded packets in this scope", "type": "integer" }, "packetCount": { "description": "distinct packets matched to this scope", "type": "integer" } } }, "github_com_MeshCore-Beacon_beacon-server_internal_api.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" }, "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" } } }, "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" } } } }, "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" } ] }