# Command API v2

This page describes how `pymirokai` sends non-mission commands to Wizard v2.

## Design Principles

- No generic `post_dict` / `post_int` / `post_str` transport in client code.
- No OpenAPI route discovery at runtime.
- Command routes are explicit in ability methods (`features/abilities/*`).

## Transport Methods

`Robot` exposes three command transport helpers:

- `send_get_command(route: str)`
- `send_post_command(route: str, value: Any = _NO_VALUE)`
- `send_command(method: str, route: str, value: Any = _NO_VALUE)`

Examples:

```python
await robot.send_get_command("/commands/get_skills/")
await robot.send_post_command("/commands/sound_level/", 50)
```

## Payload Convention

For `POST/PUT/PATCH` commands with data, payload is encoded as:

```json
{"value": "<payload>"}
```

This matches Wizard v2 command payload models.

## High-Level Usage

Prefer ability methods over raw route calls:

- `await robot.set_sound_level(50)`
- `await robot.is_seeing_human()`
- `await robot.get_detected_runes()`

These methods keep route paths centralized and typed in Python code.

## Mission-Based Skills vs Commands

- Mission-based skills (`robot.say(...)`, `robot.move_forward(...)`) create `Mission` objects.
- Command abilities (`robot.set_sound_level(...)`, `robot.get_language()`) return immediate REST responses.

## Backward Compatibility Note

`Runes.is_seeing` supports both:

- `await robot.is_seeing()` for global visibility (`GET /commands/is_seeing/`)
- `await robot.is_seeing("rune_id")` for rune-specific check (`POST /commands/is_detected/`)

This keeps older client call sites functional during migration.