Skip to main content

Data Streams

APIs for listing, reading, and writing robot data streams.


List Streams​

Returns all data streams available on a robot.

Endpoint​

GET /robots/{robotId}/streams

Request Headers​

{
"authorization": "bearer <access_token>"
}

Path Parameters​

  • robotId (string): The unique identifier of the robot.

Response Fields​

FieldTypeDescription
componentNamestringName of the component publishing the stream (may be empty for ROS topics)
streamNamestringFull stream/topic name (e.g., /scan, /cmd_vel)
streamTypestringROS message type (e.g., sensor_msgs/msg/LaserScan)
directionstringStream direction ("input", "output", or empty)
streamSourceTypeintStream source type (e.g., 3 for ROS topics)
displayNamestring|nullOptional human-readable name
sourceUrlstring|nullOptional source URL
sourceEndpointstring|nullOptional source endpoint

Response Example​

{
"robotStreams": [
{
"componentName": "",
"streamName": "/scan",
"streamType": "sensor_msgs/msg/LaserScan",
"direction": "",
"streamSourceType": 3,
"displayName": null,
"sourceUrl": null,
"sourceEndpoint": null
},
{
"componentName": "",
"streamName": "/cmd_vel",
"streamType": "geometry_msgs/msg/Twist",
"direction": "",
"streamSourceType": 3,
"displayName": null,
"sourceUrl": null,
"sourceEndpoint": null
}
]
}

Get Stream Data​

Retrieves the current data of a specific stream as a JSON string.

Endpoint​

GET /robots/{robotId}/stream?componentName={componentName}&streamName={streamName}&source={source}&streamType={streamType}

Request Headers​

{
"authorization": "bearer <access_token>"
}

Path Parameters​

  • robotId (string): The unique identifier of the robot.

Query Parameters​

  • componentName (string): The name of the component publishing the stream (may be empty for ROS topics).
  • streamName (string): The name of the stream (e.g., /scan).
  • source (int): The stream source type from the List Streams response.
  • streamType (string): The ROS message type (e.g., sensor_msgs/msg/LaserScan).

Response Example​

{
"robotStream": "{\"header\":{\"stamp\":{\"sec\":1234567890}},\"ranges\":[0.5,1.2,2.3]}"
}

Common Errors​

  • 400: streamName or source is missing, source is not 1, 2 or 3, or componentName is missing for a component stream (1).
  • 404: the robot was not found or is not accessible, or the robot has no such stream.
  • 503: the device is temporarily unreachable.

Get Empty Message Template​

Returns an empty JSON template for a given message type. Useful for constructing upload payloads.

Endpoint​

GET /streams/{messageType}/stream

Request Headers​

{
"authorization": "bearer <access_token>"
}

Path Parameters​

  • messageType (string): The message type, in ROS form (sensor_msgs/LaserScan or sensor_msgs/msg/LaserScan) or as the Nimbus.Messages.* type (Nimbus.Messages.sensor_msgs.LaserScan).

Response Example​

{
"emptyJson": "{\"header\":{\"stamp\":{\"sec\":0,\"nanosec\":0},\"frame_id\":\"\"},\"ranges\":[]}"
}

Common Errors​

  • 404: the message type is unknown.

Upload Stream​

Sends a data payload to a robot stream.

Endpoint​

POST /robots/{robotId}/upload-stream

Request Headers​

{
"authorization": "bearer <access_token>",
"Content-Type": "application/json"
}

Path Parameters​

  • robotId (string): The unique identifier of the robot.

Request Body​

This example writes to the /cmd_vel ROS2 topic from the List Streams example.

{
"componentName": "",
"streamName": "/cmd_vel",
"source": "3",
"streamJson": "{\"linear\":{\"x\":0.5,\"y\":0.0,\"z\":0.0},\"angular\":{\"x\":0.0,\"y\":0.0,\"z\":0.1}}",
"dataType": "geometry_msgs/msg/Twist"
}

Field Notes​

  • source: The descriptor's streamSourceType as a string: "1" (Nimbus component), "2" (ROS1 topic) or "3" (ROS2 topic).
  • componentName: Required for a component stream ("1"). Empty for ROS topics.
  • streamJson: JSON object serialized as a string.
  • dataType: The streamType value from the stream descriptor. The ROS form (geometry_msgs/msg/Twist) and the Nimbus.Messages.* form are both accepted.

Response​

Returns 200 OK on success with an empty body.

Common Errors​

  • 400: a required field is missing, streamJson is not valid JSON, source is not "1", "2" or "3", or dataType does not match the stream's type.
  • 404: the robot was not found or is not accessible, or the robot has no such stream.
  • 503: the device is temporarily unreachable.