Build with GuestRoute

Quickstart

Three steps. The Node SDK shown — same shape in every language.

# 1) Install
pnpm add @guestroute/node

# 2) Authenticate + dispatch
import { GuestRoute } from '@guestroute/node'

const gr = new GuestRoute({ apiKey: process.env.GR_API_KEY })

const order = await gr.orders.create({
  venue_id: 'demo-venue',
  pickup:  { unit: 'food_court_2' },
  dropoff: { unit: 'cinema_lobby' },
  compartment: 'food_hot',
})

# 3) Stream live state
for await (const event of gr.orders.stream(order.id)) {
  console.log(event.status, event.eta_s)
}

SDKs

One install per language. Path C status badges tell you exactly what's GA today and what ships next.

pod 'GuestRoute', '~> 0.2'

implementation("com.guestroute:sdk:0.2.0")

pnpm add @guestroute/viewer

apt install ros-humble-guestroute-bridge

pnpm add @guestroute/node

pip install guestroute

REST API

A taste of the surface area. Full OpenAPI + AsyncAPI specifications at docs.guestroute.com/openapi.yaml.

Authentication

One identity, scoped per venue, projected onto every wire.

Webhooks

At-least-once delivery. Retried with exponential back-off for 24 hours on non-2xx responses.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-GR-Event:     order.delivered
X-GR-Signature: t=1745689320,v1=8a3e1f...
X-GR-Delivery:  d_8C7...

{
  "event":   "order.delivered",
  "venue":   "demo-venue",
  "order":   { "id": "ord_8C3", "elapsed_s": 408, "compartment": "food_hot" },
  "robot":   { "id": "ax_0042", "battery": 0.59 },
  "ts":      "2026-04-26T14:38:09.402Z"
}

Indoor robots, on a graph they can read.

GuestRoute speaks the standards that matter — VDA 5050, ROS 2, MQTT, REST — over a single semantic indoor graph. Room functions, door policies, elevator access, time-of-day rules, occupancy. Not just geometry. The same map your visitors use, served in the format your fleet expects.

Standards we speak

Honest matrix of what's standardised in indoor robotics, what's adopted, and where GuestRoute sits. Most of the industry is fragmented vendor APIs plus ROS 2 plus custom MQTT — VDA 5050 is the only real fleet-coordination standard with traction.

The semantic graph

IMDF gives you geometry. IndoorGML gives you a graph. Neither alone is enough for a robot — you need policies, time, and adapters. Every entity in GuestRoute carries machine-readable attributes that drive routing, door handshakes, and access control.

Transports

Pick the wire that fits the integration. All five carry the same data model; authentication is unified across them.

• http
  REST Shipped

  HTTPS · JSON · Bearer

  Dispatch orders, query routes, list venues, register robots. Stateless, idempotent.

• sensors
  MQTT Shipped

  MQTT 5 · TLS 1.3 · X.509

  Live fleet state, door commands, elevator calls, VDA 5050 wire format.

• hub
  ROS 2 bridge Shipped

  DDS · Humble / Iron / Jazzy

  On-robot package. /guestroute/map · /route · /pose · /lifts · /doors.

• bolt
  WebSocket Shipped

  wss · subprotocol gr.v1

  Per-order live stream: ETA, segment progress, blockers. Browser fleet-ops dashboards.

• webhook
  Webhooks Piloting

  HTTPS POST · HMAC-SHA256

  Order state transitions, robot status change, geofence events.

REST · dispatch an order

For partners not running ROS 2 — POS systems, kiosk apps, third-party logistics platforms. One call dispatches an order; the response includes a WebSocket stream URL plus the matching VDA 5050 order ID, so you can correlate state across protocols.

# Dispatch a delivery
curl -X POST https://api.guestroute.com/v1/orders \
  -H "Authorization: Bearer $GR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "venue_id": "demo-venue",
    "pickup":  { "unit": "food_court_2" },
    "dropoff": { "unit": "cinema_lobby" },
    "robot_preference": "any_available",
    "compartment": "food_hot",
    "priority": "standard",
    "callback_url": "https://ops.example.com/gr/webhook"
  }'

# → 201 Created
# {
#   "order_id":  "ord_8C3...",
#   "robot_id":  "ax_0042",
#   "eta_s":     412,
#   "stream":    "wss://rt.guestroute.com/o/ord_8C3",
#   "vda5050":   { "order_id": "ord_8C3", "order_update_id": 0 }
# }

VDA 5050 · order shape

GuestRoute acts as the master-control role and emits VDA 5050 v2.0.0 orders to your fleet manager (or directly to the AGV when running headless). Lift and door interactions are encoded as instantActions with a HARD blocking type, so the robot waits for the platform to confirm the door is open before crossing the edge.

// Topic: uagv/v2/guestroute/ax_0042/order
{
  "headerId": 17,
  "timestamp": "2026-04-26T14:31:08.402Z",
  "version": "2.0.0",
  "manufacturer": "AutoXing",
  "serialNumber": "ax_0042",
  "orderId": "ord_8C3",
  "orderUpdateId": 0,
  "nodes": [
    { "nodeId": "n_food_court_2", "released": true,
      "nodePosition": { "x": 142.1, "y": 31.4, "mapId": "venue.l1" } },
    { "nodeId": "n_lift_a_l1",    "released": true,
      "actions": [{ "actionType": "callElevator", "actionId": "a1",
                    "blockingType": "HARD",
                    "actionParameters": [{ "key": "target_level", "value": "L3" }] }] },
    { "nodeId": "n_cinema_lobby", "released": true }
  ],
  "edges": [
    { "edgeId": "e1", "startNodeId": "n_food_court_2", "endNodeId": "n_lift_a_l1",
      "released": true, "maxSpeed": 1.2 },
    { "edgeId": "e2", "startNodeId": "n_lift_a_l1",    "endNodeId": "n_cinema_lobby",
      "released": true, "maxSpeed": 1.0 }
  ]
}

ROS 2 · topics + bridge

Native Debian package. Drop it on the robot, pass the venue and API key, and Nav2 sees a semantic-aware path. Lift and door state arrive as typed messages, so your behaviour tree can wait on a real predicate instead of polling MQTT.

# 1) Install the bridge (Humble / Iron / Jazzy)
sudo apt install ros-$ROS_DISTRO-guestroute-bridge

# 2) Launch
ros2 launch guestroute_bridge bridge.launch.py \
    venue_id:=demo-venue \
    robot_id:=ax_0042 \
    api_key:=$GR_API_KEY

# 3) Subscribe in your nav stack
ros2 topic echo /guestroute/route          # nav_msgs/Path, semantic-aware
ros2 topic echo /guestroute/lifts          # guestroute_msgs/LiftState[]
ros2 topic echo /guestroute/doors          # guestroute_msgs/DoorState[]

# 4) Publish pose for fleet visualisation
ros2 topic pub /guestroute/pose geometry_msgs/PoseStamped ...

MQTT · state stream

HiveMQ Cloud cluster (EU + KZ regions), MQTT 5 with TLS 1.3 and X.509 client certs. Wire format is VDA 5050 — the same JSON, same topic shape — so a fleet manager that already speaks 5050 connects with no translation.

# Subscribe to all robots in a venue
mosquitto_sub -h mqtt.guestroute.com -p 8883 \
  --cafile gr-ca.pem \
  -u tenant_42 -P "$GR_MQTT_TOKEN" \
  -t "uagv/v2/guestroute/+/state"

# Sample state message (VDA 5050 wire format)
{
  "headerId": 9182,
  "timestamp": "2026-04-26T14:31:14.001Z",
  "manufacturer": "AutoXing",
  "serialNumber": "ax_0042",
  "orderId": "ord_8C3",
  "lastNodeId": "n_lift_a_l1",
  "driving": false,
  "agvPosition": { "x": 142.4, "y": 31.6, "theta": 1.57, "mapId": "venue.l1" },
  "batteryState": { "batteryCharge": 0.62, "charging": false },
  "actionStates": [
    { "actionId": "a1", "actionStatus": "RUNNING",
      "actionDescription": "Calling lift A → L3" }
  ]
}

Regions & SLA