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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.theseus.us/micro-vps/autopilot-integration/developer-api/state-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.