> This page is for Firmware, version 4.0 (default).
> For other versions, use one of these documentation indexes:
> - 4.0 (default): https://docs.ouster.com/sensor-docs/firmware/4.0/llms.txt
> - 3.2: https://docs.ouster.com/sensor-docs/firmware/3.2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ouster.com/sensor-docs/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://<sensor-hostname-or-ip>/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=<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:

```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.