API Reference Overview

HTTP API for querying and configuring Ouster sensors

Ouster sensors expose an HTTP API at /api/v1 served directly from the sensor. Use it to query sensor metadata, configure the sensor, manage firmware, and retrieve diagnostics. The OpenAPI description can be read from /api/v1/openapi.yaml.

All configuration parameter names are case-sensitive. Refer to the API reference pages for exact spelling. Examples throughout this documentation are tested on Linux. macOS and Windows users should adapt the command syntax accordingly.

Base URL

Requests use the sensor’s hostname or IP address as the base:

http://<sensor-hostname-or-ip>/api/v1/

For example, a sensor with hostname os-992244000006.local:

$ curl --request GET http://os-992244000006.local/api/v1/sensor/metadata/sensor_info

Supported clients

The API accepts standard HTTP requests. Any of the following work:

Client	Notes
curl	Used in all examples throughout this documentation
HTTPie	Human-friendly CLI alternative to curl
Browser	GET endpoints are accessible directly in a web browser
REST clients	Advanced REST Client, Postman, Insomnia, etc.
Custom code	Any HTTP library (Python `requests`, Go `net/http`, etc.)

API surface

The HTTP API is organized into five resource groups:

Sensor metadata

Read-only endpoints that return fixed sensor properties — serial number, firmware version, calibration data, beam geometry, and data format descriptors.

Endpoint	Description
`GET /api/v1/sensor/metadata/sensor_info`	Serial number, firmware revision, product line, and status
`GET /api/v1/sensor/metadata/lidar_data_format`	Lidar packet structure and channel configuration
`GET /api/v1/sensor/metadata/imu_data_format`	IMU packet structure
`GET /api/v1/sensor/metadata/beam_intrinsics`	Per-beam azimuth and altitude angles
`GET /api/v1/sensor/metadata/lidar_intrinsics`	Lidar-to-sensor coordinate transform
`GET /api/v1/sensor/metadata/imu_intrinsics`	IMU-to-sensor coordinate transform
`GET /api/v1/sensor/metadata/calibration_status`	Calibration validity flags
`GET /api/v1/sensor/metadata`	All metadata fields in a single response
`GET /api/v1/sensor/mio`	Multipurpose I/O channel state (all channels)
`GET /api/v1/sensor/mio/{channel}`	Multipurpose I/O channel state (single channel)

Sensor configuration

Read and modify sensor operating parameters. A POST to /api/v1/sensor/config applies one or more parameters simultaneously and triggers reinitialization. Individual parameters can also be targeted with GET, PUT, or DELETE on their specific path.

Endpoint	Description
`GET /api/v1/sensor/config`	Active configuration
`POST /api/v1/sensor/config`	Apply one or more configuration parameters
`GET /api/v1/sensor/config/{param}`	Read a single configuration parameter
`PUT /api/v1/sensor/config/{param}`	Set a single configuration parameter
`DELETE /api/v1/sensor/config`	Reset configuration to factory defaults
`GET /api/v1/sensor/config/operating_mode`	Current operating mode (`NORMAL` or `STANDBY`)
`PUT /api/v1/sensor/config/operating_mode`	Switch operating mode

System

Restart the sensor, update firmware, and manage network settings.

Endpoint	Description
`POST /api/v1/system/restart`	Restart or reinitialize the sensor
`GET /api/v1/system/firmware`	Installed firmware version
`POST /api/v1/system/firmware`	Upload and apply a new firmware image
`GET /api/v1/system/network`	Full network configuration
`GET /api/v1/system/network/ipv4`	IPv4 address and DHCP status
`PUT /api/v1/system/network/ipv4/override`	Set a static IPv4 address
`DELETE /api/v1/system/network/ipv4/override`	Remove the static IP and revert to DHCP
`PUT /api/v1/system/network/speed_override`	Override link speed
`DELETE /api/v1/system/network/speed_override`	Remove link speed override

Time

Query PTP and system time synchronization state.

Endpoint	Description
`GET /api/v1/time`	Combined sensor and system time info
`GET /api/v1/time/sensor`	Sensor timestamp and sync mode
`GET /api/v1/time/system`	Host system clock info
`GET /api/v1/time/ptp`	PTP synchronization status
`GET /api/v1/time/ptp/profile`	Active PTP profile
`PUT /api/v1/time/ptp/profile`	Set PTP profile

Alerts and diagnostics

Retrieve active and historical alerts, download a full diagnostics bundle, and read live telemetry.

Endpoint	Description
`GET /api/v1/sensor/alerts`	Full alert log
`GET /api/v1/sensor/alerts?cursor=<n>`	Alert log starting from cursor position
`GET /api/v1/sensor/alerts?mode=summary`	Active alerts only
`GET /api/v1/diagnostics/dump`	Complete diagnostics archive (attach to support requests)
`GET /api/v1/sensor/telemetry`	Live telemetry snapshot

Quick example

Retrieve sensor info and apply a configuration change in two commands:

$ # Read sensor info
$ curl http://os-992244000006.local/api/v1/sensor/metadata/sensor_info
$ 
$ # Set lidar mode to 1024x10 and point UDP output at a host
$ curl --request POST \
>   --url http://os-992244000006.local/api/v1/sensor/config \
>   --header "Content-Type: application/json" \
>   --data '{"lidar_mode": "1024x10", "udp_dest": "192.0.2.1"}'

User-editable data

Firmware v3.1 added a user-editable data store (/api/v1/user/data) for embedding arbitrary metadata on the sensor — calibration notes, site tags, asset IDs, or any other ASCII/Unicode string up to 128 KB. This data persists across reboots and is independent of sensor configuration.

TCP API (deprecated)

The TCP API was deprecated in firmware v3.1. All supported functionality is available through the HTTP API. Contact Ouster Support if you need guidance migrating from the TCP API.