topcmesh API

Every request goes to https://bus.topcmesh.com. The mesh is versioned by header, not by path — a path version would have forced a migration on people who only wanted a bug fix.

Send Topcmesh-Version: 2026-04-01 on publish requests and as a query parameter on the WebSocket handshake. Omit it and you are pinned to the version that was current when your namespace was created, which never changes underneath you.

A topic name is a string of up to 128 characters from [a-z0-9._-]. Dots carry no meaning to the mesh — orders.status is one flat name, not a hierarchy, and there is no wildcard subscription. This is deliberate; see the capability list for why the topic space stays flat.

There are two token classes and they are not interchangeable.

• Publish tokens are long-lived, server-side only, and scoped to a namespace with an optional topic prefix. Never ship one to a browser — a publish token can write to every topic in its scope.
• Subscriber tokens are short-lived (300 seconds by default, 3,600 maximum), minted by your backend, and scoped to an explicit list of topics. These are the ones that reach clients.

Both token classes carry the same claim set. The mesh checks ns against the route on every request and topics on every attach.

One POST per message. The mesh accepts the message, assigns it a cursor, and fans it out to every connection currently attached to the topic. Publishing is synchronous with respect to acceptance and asynchronous with respect to delivery.

fanout is the number of connections the message was queued to at acceptance time. It is not a delivery confirmation — a connection can drop between acceptance and write. Per-subscriber delivery is observable in the namespace log, keyed by connection ID.

Bodies may be any content type up to 256 KB. The mesh does not inspect, transform, or re-encode the payload; Content-Type is passed through to subscribers verbatim. If you need larger objects, publish a reference and let the client fetch it.

Open one WebSocket per client and attach to as many topics as the token allows. There are four frame types and that is the entire protocol.

If you would rather not take the dependency, the raw frames are plain JSON and the whole exchange looks like this:

A cursor is an opaque, monotonically increasing six-character token scoped to a single topic. It is not a timestamp, not an offset, and not comparable across topics. Do not parse it — the encoding has changed once already and will change again.

Attach with one of three values:

• 'latest' — live only. Nothing before the moment of attach is delivered.
• '<cursor>' — resume. Everything after that cursor is replayed in order, then live delivery continues.
• 'earliest' — start from the retention floor, which is the oldest message still inside the topic's window.

On a resume the mesh emits a replay frame carrying from and count, then the gap in order, then live messages. There is no end-of-replay marker, because there is no boundary: the replayed messages and the live ones are a single ordered run, and a client that treats them identically is correct.

A cursor older than the topic's retention window returns 409 cursor_expired. This is not an outage and not a bug — it is the documented consequence of a finite buffer. The correct response is to resynchronize from your own source of truth and re-attach at 'latest'. If you find yourself hitting it routinely, the topic's retention window is set too short for how long your clients stay away.

Retention is per topic, so a high-volume telemetry topic can hold sixty seconds while a low-volume order topic holds six hours in the same namespace. Buffers are sized by time, not by message count.

Every subscriber connection has an 8 MB outbound buffer. A client that stops reading — a throttled background tab, a device on a saturated link, a process that stalled in a render loop — fills that buffer and then gets disconnected with slow_consumer and WebSocket close code 4290.

The disconnection is deliberate and it is the safe outcome. The SDK reconnects with its last acknowledged cursor, which turns a slow consumer into a replay rather than into data loss — provided it recovers inside the retention window. The alternative designs are unbounded buffering, which turns one bad client into a memory incident, or silent dropping, which is data loss without a signal.

Each event is written to the namespace log with the connection ID, the topic, the buffered byte count and the timestamp. You get the specific connection, not an aggregate you then have to go correlate against your own logs.

These are published because you should be able to model the mesh before you depend on it. Sustained operation above a tier ceiling is a conversation about tiers, not an immediate cutoff.

The mesh does not buffer publishes on your behalf. Exceeding a publish rate returns 429 publish_rate_exceeded with a Retry-After header in seconds; retrying is your call and your backoff.

Errors return a machine-readable code, a human sentence, and nothing else. There is no error taxonomy to learn beyond this table.

Three clients, all thin. They handle the reconnect loop, cursor persistence and token refresh. Everything else you would write yourself in an afternoon, and section 04 is the whole protocol if you would rather.

No SDK has a dependency beyond its standard library. The browser client ships as ESM only and has no polyfills — if your target predates WebSocket and AbortController, the raw protocol is your path.