> For the complete documentation index, see [llms.txt](https://docs.theseus.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.theseus.us/micro-vps/autopilot-integration/developer-api/state-api.md).

# State API

The State API provides a read-only snapshot of system information collected by theseus-edge-api. Use it to diagnose whether VPS is blocked by hardware, services, eCAL topics, MAVLink, time sync, or licensing.

**Default State API Base URL:** `http://192.168.218.100:5050`

If the Developer API base URL is `http://192.168.218.100:5000`, use the same host with port `5050` for these v2 state endpoints.

## MicroVPS / VIO State

To check whether MicroVPS VIO is running, use the Developer API:

```
GET http://192.168.218.100:5000/api/vio/status
```

This is the direct VIO status indicator. It returns `state: "running"` when VIO is running, `state: "stopped"` when it is not running, and `state: "not_applicable"` on EKF builds.

The v2 State API does not include a direct VIO initialized/running field. The closest v2 signal is the `vio_transformer/vio` topic in `/api/v2/state/ecal`: `publishing: true` means VIO odometry is flowing; `not_publishing` or `stale` means VIO output is not currently flowing.

All endpoints below are under `/api/v2/state`.

## System State

### Get Complete State

```
GET /api/v2/state
```

Returns one response with all available state groups.

**Response `200`:**

```json
{
  "success": true,
  "data": {
    "hardware": {},
    "services": {},
    "ecal": {},
    "mavlink": {},
    "timesync": {},
    "license": {},
    "flight_log": {},
    "vps_error": {
      "code": 0,
      "message": "System healthy"
    }
  }
}
```

`hardware` is the only required group. Other groups may be `null` or omitted if their monitor is not available.

### Get Hardware State

```
GET /api/v2/state/hardware
```

Returns voltage, CPU temperature, CPU load, memory use, disk use, mounted storage devices, internet connectivity, and camera state.

Useful for diagnosing power, thermal, storage, network, and device-level issues.

### Get Camera State

```
GET /api/v2/state/camera
```

Returns active camera stream status, device path, name, resolution, FPS, pixel format, thermal flag, config match, and health fields.

Useful for diagnosing an unplugged camera, a camera that is not streaming, or a calibration/config mismatch.

### Get eCAL State

```
GET /api/v2/state/ecal
```

Returns eCAL availability plus monitored topic publishing state, message age, staleness threshold, and topic health.

Useful for diagnosing missing or stale data between components.

### Get MAVLink State

```
GET /api/v2/state/mavlink
```

Returns MAVProxy listener status, heartbeat status, autopilot IDs, vehicle type, mode/status fields, heartbeat age/rate, port status, and health fields.

Useful for diagnosing autopilot connection loss, wrong system/component ID, or MAVProxy port issues.

### Get Time Sync State

```
GET /api/v2/state/timesync
```

Returns chrony tracking, chrony sources, MAVLink TIMESYNC convergence, recent warnings, deployed timesync params, waitsync status, and health fields.

Useful for diagnosing unsynchronized clocks, a bad time source, high RTT, invalid FCU time, or timesync startup failure.

### Get Services State

```
GET /api/v2/state/services
```

Returns monitored systemd service state, enabled state, sub-state, result, PID, memory, CPU, restart count, exit code, signal exit flag, health fields, and blockers.

Useful for diagnosing service crashes, clean stops, restart loops, and missing runtime dependencies.

## Additional Fields

The complete state response may also include:

| Field        | Information sent                                                                                                                | Useful for diagnosing                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `license`    | License validity, product, customer, tier, features, expiration, quota, hardware match, clock sync status, and error/fix fields | License missing, expired, invalid, or bound to different hardware |
| `flight_log` | Flight log status from the edge API state logger                                                                                | Whether state snapshots are being written to the flight log       |
| `vps_error`  | Current VPS error code and user-facing message                                                                                  | Quick HTTP equivalent of the MAVLink `VPS_ERR` health signal      |

Most groups include `health_status`, `health_error`, and `health_fix` when the monitor can provide a direct diagnosis.

## Error Codes

| Error Code | Reason                                                                        |
| ---------- | ----------------------------------------------------------------------------- |
| 503        | State store or requested monitor is not initialized or has no state available |

## curl Examples

```bash
# Get the complete state snapshot
curl http://192.168.218.100:5050/api/v2/state

# Check only camera state
curl http://192.168.218.100:5050/api/v2/state/camera

# Check only MAVLink state
curl http://192.168.218.100:5050/api/v2/state/mavlink

# Check all monitored services
curl http://192.168.218.100:5050/api/v2/state/services
```