Data Streams

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

---

List Streams

Cloud

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

Field	Type	Description
componentName	string	Name of the component publishing the stream (may be empty for ROS topics)
streamName	string	Full stream/topic name (e.g., /scan, /cmd_vel)
streamType	string	ROS message type (e.g., sensor_msgs/msg/LaserScan)
direction	string	Stream direction ("input", "output", or empty)
streamSourceType	int	Stream source type (e.g., 3 for ROS topics)
displayName	string|null	Optional human-readable name
sourceUrl	string|null	Optional source URL
sourceEndpoint	string|null	Optional 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
    }
  ]
}

Local

Returns all stream descriptors available on the selected robot. Requests for configured local-fleet members are proxied to the member agent.

Endpoint

GET /robots/{robotId}/streams

Request Headers

{
  "authorization": "bearer <local-api-gateway-token>"
}

Response Example

{
  "robotStreams": [
    {
      "componentName": "camera",
      "streamName": "pose",
      "streamType": "Nimbus.Messages.geometry_msgs.Pose",
      "direction": "output",
      "streamSourceType": 1,
      "displayName": "Camera pose",
      "sourceUrl": "",
      "sourceEndpoint": ""
    },
    {
      "componentName": "",
      "streamName": "/cmd_vel",
      "streamType": "Nimbus.Messages.geometry_msgs.Twist",
      "direction": "input",
      "streamSourceType": 3,
      "displayName": "",
      "sourceUrl": "",
      "sourceEndpoint": ""
    }
  ]
}

Stream Source Types

Value	Description
1	Nimbus component stream
2	ROS1 topic
3	ROS2 topic
4	ONVIF URL source
5	RTSP URL source
6	Device endpoint (e.g., /dev/video0)

ROS descriptors use an empty componentName; streamName is the real ROS topic name, and streamType is the matching Nimbus.Messages.* type. ONVIF descriptors include sourceUrl; device descriptors include sourceEndpoint.

For continuous or high-rate local reads, use the descriptor with the Live Stream WebSocket.

---

Get Stream Data

Cloud

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]}"
}

note

Returns 503 Service Unavailable if the device is temporarily unreachable.

Local

Reads one JSON message from a stream. The read waits up to one second for a message.

Endpoint

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

Request Headers

{
  "authorization": "bearer <local-api-gateway-token>"
}

Query Parameters

• componentName: Required for component streams. Empty for ROS descriptors.
• streamName: The stream or ROS topic name.
• source: Stream source type from the selected descriptor.
• streamType: Required for ROS1 and ROS2 reads.

Requests for configured local-fleet members are proxied to the member agent.

Response Example

{
  "robotStream": "{\"data\":\"ok\"}"
}

Common Errors

• 400: required query parameters are missing or invalid.
• 404: robot, stream, ROS gateway, or stream type was not found.
• 408: no message arrived before the one-second read timeout.

---

Get Empty Message Template

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

Cloud

Endpoint

GET /streams/{messageType}/stream

Request Headers

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

Path Parameters

• messageType (string): The ROS message type (e.g., sensor_msgs/LaserScan).

Response Example

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

Local

Endpoint

GET /streams/{messageType}/stream

Request Headers

{
  "authorization": "bearer <local-api-gateway-token>"
}

Path Parameters

• messageType (string): The Nimbus.Messages.* type (e.g., Nimbus.Messages.geometry_msgs.Pose).

Response Example

{
  "emptyJson": "{\"header\":{\"frameId\":\"map\"}}"
}

---

Upload Stream

Sends a data payload to a robot stream.

Cloud

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

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

Response

Returns 200 OK on success with an empty body.

Local

Endpoint

POST /robots/{robotId}/upload-stream

Request Headers

{
  "authorization": "bearer <local-api-gateway-token>",
  "Content-Type": "application/json"
}

Request Body

{
  "componentName": "data-publisher",
  "streamName": "gps",
  "source": "1",
  "streamJson": "{\"x\":\"1\",\"y\":\"2\",\"z\":\"3\"}",
  "dataType": "Nimbus.Messages.geometry_msgs.Point"
}

Field Notes

• streamJson: JSON object serialized as a string.
• dataType: Use the streamType value from the stream descriptor.
• For ROS1/ROS2 uploads, send back the streamType from the descriptor as dataType — the API does not guess ROS topic types.

Response

Returns 200 OK on success with an empty body.

Common Errors

• 400: required fields missing, JSON invalid, source unsupported, or dataType mismatch.
• 404: robot, stream, ROS gateway, or stream type not found.