{ "openapi": "3.1.0", "info": { "title": "txmesh Public API", "version": "3.0.0", "summary": "The unauthenticated HTTP surface of txmesh — the pathbot submit/read API, the public alert configuration feed, the session endpoints, and the static page shells.", "description": "txmesh (`https://txme.sh`) is a MeshCore mesh telemetry archive, bot framework and\n\"pathbot\". This document describes **only the surface a third party can call without a\nsession cookie**. Everything else in the application — the browsable path list, node\nand topology queries, message history, bot administration, the mesh send bridge and all\n`/api/admin/*` routes — requires a session and is deliberately excluded.\n\n## Who this is for\n\n* **Third-party `!path` bots.** Another operator's bot can hand its hop chains to\n `POST /api/device/path` and get back a short, shareable map link instead of building\n its own resolver, storage and map page.\n* **Observer firmware.** The `combined_node` firmware and anything like it submits over\n the same endpoint; the response is deliberately tiny because the reply rides a\n ~160-character LoRa text frame.\n* **Map consumers.** `GET /api/path/{slug}/geojson` returns an RFC 7946\n FeatureCollection that drops straight into Leaflet, MapLibre, geojson.io, or an\n existing GeoJSON pipeline.\n\n## Access model\n\n* **Reading a path is public by default.** The three `GET /api/path/...` endpoints and\n the `GET /p/{slug}` page are open to anonymous callers while the deployment's\n `PATH_VIEW_PUBLIC` env var is true (the default, and what `txmesh` runs). When it is\n false, an anonymous caller gets `401 {\"error\":\"authentication required\"}` from the\n JSON endpoints and a `303` redirect to `/login` from the HTML page.\n* **Writing a path requires a sender identity.** `POST /api/device/path` accepts, in\n strict precedence order: a static `x-device-token`, an `x-meshcore-pubkey` header, or\n — only when the deployment sets `DEVICE_PATH_OPEN=true`, which is **not** the default\n — the client IP. With none of those it returns `403`.\n* **`x-meshcore-pubkey` is membership, not authentication.** MeshCore public keys are\n broadcast over the air and are not secret, so any caller can assert any node's key.\n This is a deliberate, accepted tradeoff to keep the submit API open; treat it as a\n grouping/attribution key, never as a credential. Only `x-device-token` is a real\n secret (matched in constant time).\n* **Anonymous viewers get coarsened coordinates.** The two device-supplied endpoint\n coordinates (the reporting node's and the requesting node's positions) are rounded to\n `PATH_ANON_COORD_DECIMALS` decimals — 2 by default, roughly a 1 km grid — for callers\n with no session, and the response flags this with `coordsRounded`. Untrusted senders\n additionally have those two coordinates rounded **irreversibly at ingest**. Per-hop\n repeater coordinates come from the roster/advert archive and are never coarsened.\n* **Sessions are cookies.** `POST /auth/login` and `POST /auth/register` set an\n `ms_session` cookie (HttpOnly, Secure, SameSite=Lax). Only the SHA-256 of the token is\n stored server-side. There is no bearer-token or API-key alternative for reads.\n\n## Things that will bite an integrator\n\n* **No CORS.** The application installs no CORS middleware, so there are no\n `Access-Control-Allow-*` headers and no preflight handling. Browser JavaScript on\n another origin cannot call any of these endpoints. This is a server-to-server,\n device-to-server and native-client API; proxy it if you need it in a browser.\n* **Three different error envelopes.** The pathbot routes return `{\"error\": \"...\"}`, the\n auth routes return FastAPI's `{\"detail\": \"...\"}`, and request-body validation failures\n return FastAPI's `{\"detail\": [ ... ]}` array. They are not unified — check the\n operation you are calling.\n* **Path responses are re-resolved on every read.** Only the submitted inputs are\n stored; hop hashes are matched against the live roster at view time. The same slug can\n legitimately return more resolved hops, different coordinates and a different\n `totalKm` tomorrow than it does today. Do not treat a response as immutable and do not\n cache it indefinitely.\n* **Submitted paths are deleted after the retention window.** A housekeeping loop runs\n every 6 hours and deletes `device_paths` rows older than `DEVICE_PATH_RETENTION_DAYS`\n (**7** by default), after which the slug returns `404` from every JSON endpoint and\n drops out of other reports' `related` lists. A shared `/p/` link is therefore good\n for about a week — treat one as ephemeral, and re-submit the hop chain if you need\n a durable record.\n* **Rate limiting is per sender, not global.** See `POST /api/device/path`. The read\n endpoints are not rate limited by the application at all.\n* **HEAD is mostly not answered.** Contrary to what this document said before\n 2026-07-26, routes here are declared `GET`-only — FastAPI's router, unlike Starlette's,\n does not add `HEAD` for you — and a `HEAD` falls through to the catch-all static mount,\n which answers `404` unless a file of that name exists. The exceptions are the four\n documentation routes (`/docs/api`, `/docs/api/reference` and the two spec files), which\n answer `HEAD` explicitly because tooling probes a spec URL before fetching it. Probe\n with `GET` everywhere else; a `404` from a `HEAD` says nothing about whether the\n resource exists.\n* **Response headers.** Every routed response carries\n `Content-Security-Policy` (restricts script/connect/form/base/object origins),\n `Strict-Transport-Security: max-age=31536000; includeSubDomains`,\n `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff` and\n `Referrer-Policy: strict-origin-when-cross-origin`. `Cache-Control: no-cache` is added\n only to `text/html`, `text/css` and JavaScript responses — the JSON API carries no\n cache directive at all. Unhandled 500s (for example postgres being unreachable) are\n produced outside that middleware, so they are `text/plain` and carry none of those\n headers.\n* **This document is hand-written, and it is served.** Fetch it from\n `GET /docs/api/openapi.yaml` or `GET /docs/api/openapi.json` — those two routes are the\n only ones in the application that send `Access-Control-Allow-Origin: *`, so browser\n tooling can load them by URL (the endpoints they describe stay CORS-less). A rendered\n reference lives at `GET /docs/api/reference` and the prose walkthrough at\n `GET /docs/api`. FastAPI's own `/docs`, `/redoc` and `/openapi.json` are **disabled**\n (`openapi_url=None`) — they described the *entire* surface, session-gated admin routes\n included — and all three return `404`.\n* **A catch-all static mount backs `/`.** After the API routes, the whole `web/`\n directory is mounted unauthenticated (`StaticFiles(..., html=True)`), so every shell\n and asset is also reachable by filename — `/index.html`, `/landing.html`,\n `/path.html`, `/node.html`, `/observer.html`, `/theme.css?v=N`, `/theme.js?v=N` and\n the rest. Those files are data-free (all data still comes from the JSON API), and the\n routes documented below win because they are registered first, but note that\n `GET /index.html` bypasses the anonymous/signed-in branch that `GET /` performs. No\n path items are listed for them.\n\nBehaviour that depends on deployment configuration is called out inline with the env var\nthat controls it. The defaults quoted here are `meshscope/config.py` defaults, not\nguarantees about any particular cluster.\n\nAPI version `3.0.0` above is the *application's* version (from `pyproject.toml`); this\ndocument is written against **OpenAPI 3.1.0**. The two numbers are unrelated.", "contact": { "name": "txmesh", "url": "https://txme.sh", "email": "hello@txme.sh" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://txme.sh", "description": "This deployment's public base URL, as configured in Admin -> Site. Generated /p/ links use it." } ], "tags": [ { "name": "pathbot", "description": "The `!path` integration surface: submit a hop chain, then read it back as JSON, as\nGeoJSON, or as a hosted HTML map page. This is the part of txmesh that was\ndeliberately opened for third-party adoption." }, { "name": "auth", "description": "Session endpoints. Public in the sense that they carry no authentication dependency —\nthey are how a session is created, destroyed, or probed." }, { "name": "system", "description": "Health probing and the public alert-configuration feed." }, { "name": "pages", "description": "Static HTML shells served by the API. They contain no data; their JavaScript calls the\nJSON API. Documented for completeness — an integrator wants the JSON endpoints." } ], "security": [], "paths": { "/api/device/path": { "post": { "tags": [ "pathbot" ], "operationId": "submitDevicePath", "summary": "Submit a MeshCore !path hop chain and get back a short hosted map URL", "description": "Stores a `!path` hop-hash chain plus optional endpoint coordinates, node names and\nper-hop SNRs; resolves the hop hashes against the roster/advert archive; mints a\n7-character slug; and returns the URL of the hosted map page `/p/{slug}` (run\nthrough a shortener when this deployment shortens for you — see below).\n\nOnly the **inputs** are stored. Hop hashes are re-resolved every time the path is\nviewed, so a link improves on its own as the roster learns about more repeaters.\n\n### Sender identity (required)\n\nEvaluated in this exact precedence, and a non-matching value simply falls through to\nthe next branch rather than erroring:\n\n1. `x-device-token` — an env-configured (`DEVICE_TOKEN`) or admin-issued token. A\n match makes the sender\n **pre-trusted**: its coordinates are stored at full precision. A token header that\n does not match is *not* an error; there is no \"invalid token\" response.\n2. `x-meshcore-pubkey` — hex, optional leading `!`, case-insensitive, 8–64 hex\n characters; only the lowercase 8-hex prefix is used. **Membership, not\n authentication** — public keys are broadcast on the mesh, so anyone can assert\n anyone's key. Accepted whether or not that key has actually been heard on the\n mesh (the server records \"known?\" purely so an admin can make a trust call).\n3. Client IP — only when the deployment sets `DEVICE_PATH_OPEN=true` (default\n **false**). The IP is the *rightmost* `X-Forwarded-For` entry (appended by the\n trusted proxy), falling back to the peer address.\n\nWith none of the three, the request is rejected `403`. A typo'd token therefore\nsurfaces as either a `403` or a silent downgrade to coarsened coordinates — never as\nan explicit error.\n\nThe `security` block below lists only the two identities a default deployment\naccepts. The third, client-IP branch is conditional on `DEVICE_PATH_OPEN=true` and a\nsecurity requirement cannot carry that condition, so it is described here rather\nthan advertised as an unauthenticated alternative — do not read its absence as\nproof that a particular deployment rejects anonymous submissions.\n\n### Short links\n\nBy default the response `url` is the full `/p/{slug}` link on this deployment. Two\nthings can shorten it, and neither is on for a new sender:\n\n1. A site-wide `URL_SHORTENER`, which shortens for every sender. Not set on\n `txmesh`.\n2. A **per-sender opt-in** an admin ticks in Admin → Path senders, which sends that\n one sender's links through `URL_SHORTENER_OPTIN` (`https://da.gd/shorten?url=` by\n default). Ask if you want it — the reply rides a ~160-character LoRa frame and\n roughly six characters are on offer.\n\nShortening is best-effort: a 2-second cap, and any failure falls back to the full\nURL, so `url` is always a working link but is **not guaranteed to be short** even\nwith the opt-in on. Whichever form comes back is persisted and reused by the\n15-minute retry dedupe. Note that shortening hands the trace URL to a third party.\n\n### Coordinate precision\n\nStatic-token senders and admin-trusted senders store `o`/`q` precisely. Everyone\nelse's `o` and `q` are rounded to `PATH_ANON_COORD_DECIMALS` decimals (2 by default,\nroughly 1 km) **before they are written**. That is destructive: the precise value is\nnever stored and cannot be recovered.\n\n### Validation asymmetry\n\nOnly `h` can fail the request. A malformed or out-of-range `o`, `q` or `s` is\nsilently dropped (the anchor or the SNR set simply becomes null) — a `200` does not\nmean every field you sent was accepted. `s` in particular is discarded wholesale\nunless it has exactly one value per hop and every value is within ±40 dB.\n\n### Idempotency\n\nA byte-identical logical resubmission (same hashes, same coordinates, same names)\nwithin **15 minutes** reuses the existing row: the same slug comes back, no new row\nis created, and no additional rate-limit budget is consumed. The previously issued\nshort URL is reused when one was persisted — if the original shortening failed, or\nnothing was shortening this sender's links, nothing was stored and the retry attempts\nshortening again. Firmware re-asks when the LoRa reply is lost, so treat this endpoint as\nidempotent-within-15-minutes rather than adding your own dedupe, and never assume a\nfresh slug per call.\n\n### Evaluation order (observable)\n\nBody validation (422) → identity (403) → rate limit (429) → hash validation (400) →\ndatabase writes. An anonymous caller with a malformed body sees `422`, not `403`; a\nrate-limited caller with bad hashes sees `429`, not `400`.\n\n### Compatibility guarantee\n\nThe success body must keep the literal `\"url\":\"...\"` shape — deployed firmware finds\nit with `strstr`, not a JSON parser. It will never be renamed or nested.\n\nContent type may be `application/json`, any `application/*+json`, or **absent**\n(which is what constrained firmware usually sends). Any other content type is a\n`422`. Unknown JSON keys are ignored.", "security": [ { "deviceToken": [] }, { "meshcorePubkey": [] } ], "requestBody": { "required": true, "description": "Single-letter wire format — the sender is a microcontroller building JSON with snprintf into a 256-byte buffer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePathSubmission" }, "examples": { "firmware": { "summary": "Two-hop report with both endpoints and SNRs", "value": { "h": "90e2,fe27", "o": "30.267153,-97.743061", "q": "30.5083,-97.8203", "n": "TX-Hill Repeater", "r": "kk5abc", "s": "11.5,-3.25" } }, "minimal": { "summary": "Hop chain only — everything else is optional", "value": { "h": "90e2" } } } } } }, "responses": { "200": { "description": "Stored (or deduped onto an existing row within the 15-minute window). Exactly\n`url` and `resolved`, plus `km` when the resolver produced a total length.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePathAccepted" }, "examples": { "resolved": { "summary": "One hop resolved, both endpoints known", "value": { "url": "https://txme.sh/p/RiYpPco", "resolved": 1, "km": 41.8 } }, "nothingResolved": { "summary": "No hop resolved and no endpoint coordinates — `km` is absent, not null", "value": { "url": "https://txme.sh/p/RiYpPco", "resolved": 0 } } } } } }, "400": { "description": "`h` failed validation — non-hex, an odd hash width, a hash longer than 3 bytes\n(over 6 hex characters), mixed widths within one chain, empty, or more than 64\nhops. Raised before any sender row is created, so a garbage submission never\nregisters a sender.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "bad hashes" } } } }, "403": { "description": "No sender identity: no configured token matched `x-device-token`,\n`x-meshcore-pubkey` was missing or not a plausible key, and `DEVICE_PATH_OPEN`\nis false. This is the default posture — leaving `DEVICE_TOKEN` unset must not\nsilently open a write endpoint to the internet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "submission requires a device token or a mesh pubkey" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/DeviceRateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/path/{slug}": { "get": { "tags": [ "pathbot" ], "operationId": "getPath", "summary": "Resolved !path report as JSON", "description": "Returns one stored report, re-resolved at read time against the live roster:\nper-hop node identification with coordinates, the two device-supplied endpoint\npositions, and path-length statistics. This is the richest of the three public path\nviews and is exactly what the `/p/{slug}` HTML page fetches.\n\nThe hop chain is in traversal order, requester side first. Resolution happens per\nrequest, so the same slug can return more resolved hops and a different `totalKm`\nlater — responses are not stable and should not be cached indefinitely.\n\nAnonymous callers get `origin` and `requesterPos` rounded to\n`PATH_ANON_COORD_DECIMALS` decimals (2 by default, roughly 1 km) and\n`coordsRounded: true`. Note the flag means \"read-time coarsening was applied\", not\n\"the numbers changed\" — re-rounding an already-coarse coordinate is a no-op — and it\nis false when the report stores no endpoint coordinates at all. Per-hop repeater\ncoordinates are archive data and are always full precision.\n\nPublic while `PATH_VIEW_PUBLIC` is true (the default). When it is false, an\nanonymous caller gets `401` *before* the slug is looked up, so the endpoint cannot\nbe used to enumerate slugs. A session cookie is optional; when present it also\nsuppresses the read-time coarsening.\n\nNot rate limited.", "security": [ {}, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "The stored report, resolved against the current roster.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathReport" }, "example": { "slug": "RiYpPco", "createdAt": "2026-07-24T15:04:05.123456+00:00", "reporter": "TX-Hill Repeater", "requester": "kk5abc", "origin": { "lat": 30.27, "lon": -97.74 }, "requesterPos": { "lat": 30.51, "lon": -97.82 }, "reporterNode": { "nodeId": "9f2c81ab", "shortId": "9f2c81ab", "role": "repeater", "lastSeen": "2026-07-24T14:58:00+00:00", "batteryMv": null }, "requesterNode": null, "coordsRounded": true, "snrs": [ 11.5, -3.25 ], "sentTs": null, "rxTs": null, "delayS": null, "hops": [ { "hash": "90e2", "name": "Pflugerville Relay", "nodeId": "90e2c47f", "shortId": "90e2c47f", "role": "repeater", "lat": 30.4394, "lon": -97.7908, "lastSeen": "2026-07-24T14:51:00+00:00", "batteryMv": null, "candidates": 2, "alternates": [ { "name": "Gulf Coast 90e2", "nodeId": "90e2f011", "shortId": "90e2f011", "role": "repeater", "lastSeen": "2026-07-22T02:14:00+00:00", "kmAway": 312.4, "meshIds": [ 2 ] } ], "segmentKm": 8.9, "meshIds": [ 1 ], "meshAmbiguous": true }, { "hash": "fe27", "name": null, "candidates": 0, "possible": [ { "nodeId": "fe2790b4", "name": "fe2790b4", "shortId": "fe2790b4", "lastSeen": "2026-07-19T18:02:00+00:00" } ] } ], "resolved": 1, "totalKm": 27.6, "originKm": 18.7, "suspectSegments": 0, "meshId": 1, "meshInferred": false } } } }, "401": { "$ref": "#/components/responses/PathAuthRequired" }, "404": { "$ref": "#/components/responses/PathNotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/path/{slug}/geojson": { "get": { "tags": [ "pathbot" ], "operationId": "getPathGeoJson", "summary": "Resolved !path report as an RFC 7946 GeoJSON FeatureCollection", "description": "The same resolved path, shaped for map tooling. Emits one `Point` per **positioned**\nhop plus one `Point` per known endpoint anchor, and a `LineString` tracing\nrequester → hops → reporter in traversal order. Unresolved hops carry no position,\nso both the points and the line skip them (and `seq` on hop features consequently\nhas gaps — it is the index into the full hop list).\n\nServed with media type `application/geo+json`. Error responses are plain\n`application/json`.\n\nIdentifiers (slug, canonical page URL, node names, counts) ride along in a\n`metadata` **foreign member** on the FeatureCollection — non-standard but permitted\nby RFC 7946 — so a consumer needs no second request. All eight metadata keys are\nalways present; any of them may be null.\n\nTwo shape rules that trip people up:\n\n* `Point` feature properties are filtered of nulls, so every property except `role`\n is **absent** rather than null when unknown. (`seq: 0` survives — the filter drops\n null, not falsy.)\n* The `LineString` properties are *not* filtered, so all four keys are always\n present and may be null.\n\nCoordinates are `[longitude, latitude]` (RFC 7946), while the JSON view's `origin`\nand `requesterPos` use `{\"lat\": …, \"lon\": …}`. Two conventions in one API — mind the\norder. There is no CRS member; coordinates are WGS 84. There is no altitude element.\n\nThe `LineString` appears only when at least two points were collected, so a\nsingle-hop path with no endpoints yields one feature and no line.\n\nThis representation carries **no `coordsRounded` flag** even though the identical\nanonymous coarsening was applied to the requester/reporter anchors — call\n`GET /api/path/{slug}` if you need to know.\n\nDistances (`metadata.totalKm`, the LineString's `totalKm`, each hop's `segmentKm`)\nare always computed from the precise stored coordinates, before that coarsening is\napplied to the requester/reporter anchors. For an anonymous caller they therefore do\nnot match what you get by measuring the emitted geometry — do not use them as a\nchecksum.\n\nSame access model as `GET /api/path/{slug}`: public while `PATH_VIEW_PUBLIC` is\ntrue, optional session cookie, not rate limited.", "security": [ {}, { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "A GeoJSON FeatureCollection with a `metadata` foreign member.", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/PathFeatureCollection" }, "example": { "type": "FeatureCollection", "metadata": { "slug": "RiYpPco", "url": "https://txme.sh/p/RiYpPco", "createdAt": "2026-07-24T15:04:05.123456+00:00", "reporter": "TX-Hill Repeater", "requester": "kk5abc", "hopCount": 2, "resolved": 1, "totalKm": 27.6 }, "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -97.82, 30.51 ] }, "properties": { "role": "requester", "name": "kk5abc" } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -97.7908, 30.4394 ] }, "properties": { "role": "hop", "seq": 0, "hash": "90e2", "name": "Pflugerville Relay", "nodeId": "90e2c47f", "nodeRole": "repeater", "lastSeen": "2026-07-24T14:51:00+00:00", "segmentKm": 8.9 } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -97.74, 30.27 ] }, "properties": { "role": "reporter", "name": "TX-Hill Repeater" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [ -97.82, 30.51 ], [ -97.7908, 30.4394 ], [ -97.74, 30.27 ] ] }, "properties": { "role": "path", "slug": "RiYpPco", "totalKm": 27.6, "resolved": 1 } } ] } } } }, "401": { "$ref": "#/components/responses/PathAuthRequired" }, "404": { "$ref": "#/components/responses/PathNotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/path/{slug}/related": { "get": { "tags": [ "pathbot" ], "operationId": "getPathRelated", "summary": "Other !path reports by the same requester", "description": "Lists other reports made by the same requester — the mesh user who ran `!path` —\nfor the \"more from this node\" rail on the `/p/` page.\n\nGrouping prefers **public key**: the requester's name is resolved to its 8-hex\npubkey, then every name that pubkey is known by is unioned, so a node that renamed\nitself still groups as one identity and two different pubkeys that merely share a\ndisplay name never merge. Both the lookup and the name union read the contact-card\nroster (`contacts`) only — unlike hop resolution, adverts are not consulted, so a\nnode known only from advert beacons yields `pubkey: null` / `byPubkey: false` even\nwhen the same node resolves as a hop. Channel `!path` messages carry only the\nsender's name, so a requester with no contact card falls back to exact-name\nmatching. `byPubkey` tells you which happened — surface the distinction, because\nname matching both misses renames and is the weaker signal.\n\nResults are additionally scoped to the **submitting sender of the reference slug**\n(its `token: