HTTP Interface

The HTTP REST API provides access to almost any functionality of the PlatformPilot via the HTTP protocol.

The HTTP server is enabled by default on port 8888, however it can be disabled by setting enable_http_server to false.

The REST API is available on the path http://localhost:8888/api/. (replace localhost with your target machine)

See also HttpProxy.


Some functionality requires special permissions, see User Management.

To gain necessary permissions you need to login to the HTTP server as follows:

curl -I "http://localhost:8888/server/login?user=neo-user&passwd_plain=neobotix"
HTTP/1.1 200 OK
Set-Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8; Path=/; Max-Age=86400; SameSite=Strict;

The response will contain a session cookie which can be used as follows:

curl -H "Cookie: hsid=7ac1b14c66b6f323-0000d026d3eff249-2d4c9774cd3accb8" http://localhost:8888/api/request/...


All modules of the PlatformPilot are available via the path /api/request/.

To get an overview of the available modules:

curl http://localhost:8888/api/request/
["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "HybridPlanner/", ...]

The available methods of a module can be queried as follows:

curl http://localhost:8888/api/request/HybridPlanner/
["append_goal", "append_goal_position", "append_goal_positions", "append_goal_station", ...]

A method can be called as follows:

curl -X POST http://localhost:8888/api/request/PilotServer/get_state
{"__type": "pilot.PilotState", ...}

curl -H "Cookie: ..." -X POST -d '{"name": "Station1"}' \

The parameters of a function are supplied as a JSON object via POST data.

You may need to be logged in to access certain functions, see above.


Almost all topics of the PlatformPilot are available via the path /api/topic/.

To get an overview of the available topics:

curl http://localhost:8888/api/topic/
["input/", "local_planner/", "navigation/", "platform/", "sensors/", "task_handler/", "tf/", "tfd/", "vnx/"]

curl http://localhost:8888/api/topic/platform/
["info", "odometry", "pilot_state", "system_state"]

To get the latest sample data of a topic:

curl http://localhost:8888/api/topic/platform/odometry
{"__type": "pilot.Odometry", "time": 1613656049067588, ...}

To get a tree of the lastest sample data of a domain:

curl http://localhost:8888/api/topic/platform
{"info": {"__type": "pilot.PlatformInfo", ...}, ...}

To publish a data sample on a topic:

curl -H "Cookie: ..." -X POST -d '{"topic": "test.topic", "sample": {"__type": "pilot.Pose2D", ...}}' \

Note that a __type field needs to be specified containing the type name of the sample, such as pilot.Pose2D for example.


The current configuration tree can be viewed via the path /api/config/.

To access protected configuration values, a special permission PROTECTED_CONFIG is required, see vnx.permission_e.

To get an overview of the available config options:

curl http://localhost:8888/api/config/
["GlobalCostMap/", "GlobalPlanner/", "GridLocalization/", "GridMapping/", ...]

curl http://localhost:8888/api/config/GridLocalization/
["broadcast_tf", "confidence_gain", "constrain_threshold", "constrain_threshold_yaw", "gain_factor", ...]

To query a specific config value:

curl http://localhost:8888/api/config/GridLocalization/gain_factor

To query a sub-tree of the configuration:

curl http://localhost:8888/api/config/GridLocalization
{"broadcast_tf": true, "confidence_gain": 0.01, "constrain_threshold": 0.1, "constrain_threshold_yaw": 0.2, "gain_factor": 0.01, ...}

To query the entire configuration tree:

curl http://localhost:8888/api/config


The terminal output log messages are available via the path /api/log/.

Each message is of type vnx.LogMsg.

To get all errors which occured since startup:

curl http://localhost:8888/api/log/errors

To get all recent messages:

curl http://localhost:8888/api/log/recent
{"1": [...], "2": [...], "3": [...], "4": [...]}

To get recent warnings only:

curl http://localhost:8888/api/log/recent/2

The log levels are as follows:

  • 1 = ERROR
  • 2 = WARN
  • 3 = INFO
  • 4 = DEBUG

Log messages are also written to disk and can be accessed via http://example:8888/user/data/logs/.


A history of events is available via the path /api/events/.

Each entry is of type pilot.Event or any of it’s derived types such as pilot.Incident.

To get a list of recent events:

curl http://localhost:8888/api/events/recent

To get recent error events only:

curl http://localhost:8888/api/events/errors

The latest events are at the end of the respective list.


For certain data types there are special views available via the path /api/view/.

To get a cost map (see pilot.CostMapData) as a PGN image:

curl "http://localhost:8888/api/view/cost_map?topic=navigation.local_cost_map&color=true&alpha=128" > local_cost_map.png

To get a grid map (see pilot.OccupancyMapData) as a PGN image:

curl "http://localhost:8888/api/view/occupancy_map?topic=navigation.grid_map&alpha=255" > grid_map.png