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": null,
      "sourceUrl": null,
      "sourceEndpoint": null
    },
    {
      "componentName": "",
      "streamName": "/cmd_vel",
      "streamType": "Nimbus.Messages.geometry_msgs.Twist",
      "direction": "input",
      "streamSourceType": 3,
      "displayName": null,
      "sourceUrl": null,
      "sourceEndpoint": null
    }
  ]
}

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. The optional displayName, sourceUrl, and sourceEndpoint fields are null for ordinary component and ROS descriptors. They are populated only where applicable for video discovery.

List discovery returns ONVIF sources (4) and device endpoints (6) when they are available. RTSP sources (5) are caller-supplied when opening a live WebSocket and are not returned by discovery. Unary REST read and upload support only component, ROS1, and ROS2 sources (1–3); video sources (4–6) are supported only by the Live Stream WebSocket.

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 the next JSON message from a stream. After its temporary listener is active, the read waits up to two seconds for a message; it does not replay an earlier unlatched message. For a ROS read, the agent creates the required output gateway if one does not exist, or reuses a compatible existing gateway. Gateway resolution and startup happen before the two-second message timeout, so the total HTTP request can take longer than two seconds.

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.

Unary reads support only source types 1–3. Use the Live Stream WebSocket for source types 4–6.

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 two-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": "{\"position\":{\"x\":0,\"y\":0,\"z\":0},\"orientation\":{\"x\":0,\"y\":0,\"z\":0,\"w\":0}}"
}

---

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.
• Unary uploads support only source types 1–3. Use the Live Stream WebSocket for source types 4–6.
• 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.