MeshAPI 0.1: Specification
MeshAPI is OpenAPI for Reticulum: a manifest describing a service's ops, plus conventions for discovery, auth, and interactive docs rendered as micron pages. If OpenAPI and Swagger are to HTTP, MeshAPI is to RNS and micron.
1. The manifest
A single object, serialized as umsgpack on the wire (JSON is the canonical human form).
{
"meshapi": "0.1",
"service": { "name": "...", "summary": "...", "description": "...",
"app": "...", "aspect": "...", "path": "...",
"dest": "<hex>", "encoding": "umsgpack", "source": "https://..." },
"ops": [ { "op": "...", "summary": "...", "auth": "none",
"request": { "field": "type" }, "response": { "field": "type" } } ]
}
service
• name, summary: identity and one-liner
• description (optional): a fuller paragraph, shown atop the docs
• app, aspect: the RNS destination app_name and aspect(s)
• path: the request-handler path clients call
• dest: destination hash (hex); advisory, clients pin their own
• encoding: body encoding (umsgpack for 0.1)
• source: public source URL, never an internal git host
ops
• op: the operation selector, sent as {"op": "...", ...}
• summary: one line. auth: none, identified, or allowlist
• request: object of field to type. response: object, or a string shape like "[{lat,lon,label}]"
• limits (optional): free-form notes
type mini-language
float, int, str, bool; arrays [lat,lon] or [{...}]. Suffix ! means required, ? means optional, <=N means max. A field is a type string, or an object {type, desc}. Types drive docs and form generation. The SERVICE is always the authority and MUST validate independently. Never trust the manifest as input validation.
2. Discovery, the mesh /openapi.json
Every service answers a reserved op on its request path:
request: {"v": <n>, "op": "__manifest__"}
response: {"v": <n>, "ok": true, "manifest": <the manifest>}
It is answered regardless of envelope version, so a client can introspect before it knows your "v". A service SHOULD also serve the same manifest, human-rendered, as a micron page.
3. Auth (RNS-native identity)
• none: open read; anyone may call
• identified: client must link.identify(); service checks get_remote_identity()
• allowlist: identified AND the identity hash is on the service's allow-list
It is enforced by the service before doing work; the manifest only advertises it.
Note: a NomadNet executable "try it" runs on the NODE, not in the user's client, so its requests carry the node's identity, not the user's. Per-user identity auth requires the user's own client.
4. Interactive docs (Swagger UI for the mesh)
An executable micron page that (1) renders the service and every op with request and response schema and auth, (2) shows an input field per request param plus a run link, and (3) on submit makes a real RNS Link request to the service. It never shortcuts to the backend, which would bypass the service's validation, rate-limiting and auth. The reference package generates this from the manifest, so docs and the live form cannot drift. Field names are namespaced <op>_<param> so the page knows which op was submitted.
5. Serialization
Default wire is plain umsgpack (floats permitted; coordinates need them). A future signed-manifest profile MAY use canonical msgpack plus Ed25519 digests; that is out of scope for 0.1. Reticulum already authenticates and encrypts every link and message, so 0.1 adds no payload-level crypto.
6. Versioning
meshapi is the manifest version (0.1). The service's own envelope keeps its own v. Unknown versions: degrade to what you understand.
7. Prior art
MeshAPI is a description layer, separate from any building framework (the OpenAPI and Swagger versus web-framework split). FreeTAKTeam's Reticulum_OpenAPI is a service-building framework (archived 2026) with no mesh-native description format. MeshAPI closes that gap: one manifest is the single source of truth for machine discovery and human docs; it describes requests and responses; it has a versioned envelope, a first-class error channel, and per-op identity auth.
Source https://github.com/wdunn001/meshapi