> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ouster.com/sensor-docs/firmware/4.0/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ouster.com/sensor-docs/_mcp/server. # API Reference Overview 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`. > **Note** > > 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:///api/v1/ ``` For example, a sensor with hostname `os-992244000006.local`: ```shell 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=` | 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: ```shell # 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](https://ouster.com/tech-support) if you need guidance migrating from the TCP API. > HTTP API for querying and configuring Ouster sensors