> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.cruzcontrol.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.cruzcontrol.app/_mcp/server.

# Wash API Overview

> Overview of the MCWW Wash API for tunnel controller integration (MCWW and Washlink).

# Wash API

Default listen port is `4444`. There is no application authentication — restrict access with firewall / VLAN.

## Base URL

```
http://{controller_ip}:{port}
```

## Endpoint Groups

| Group                   | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| **Connection**          | Connectivity checks and API/controller version info               |
| **Vehicle Status**      | Photo-eye / vehicle processing state (**MCWW only**)              |
| **Wash Operations**     | Send wash packages and read wash counts                           |
| **Tunnel Control**      | Pause/restart, wetdown, conveyor request, stall on/off            |
| **Hot Dolly**           | Toggle Hot Dolly (Washlink Off is unsupported)                    |
| **Grand Entrance Arch** | Package / entrance / instructional lights (**MCWW only**)         |
| **System**              | Output sync and asset map (**MCWW only**)                         |
| **Diagnostics**         | Ops dumps gated by `DIAGNOSTIC_MODE=true`                         |
| **Deprecated**          | Legacy conveyor endpoints — use `ConveyorRequest` / `PauseTunnel` |

## Mode matrix (same URL ≠ same behavior)

| Path                                             | MCWW                                                                                | Washlink                                                                                                             |
| ------------------------------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `POST /ConveyorRequest`                          | Live Modbus conveyor request                                                        | Live Snap7 start conveyor                                                                                            |
| `POST /ConveyorOn\|Off\|Auto`                    | `DEPRECATED` / JSON **500**                                                         | Same — use ConveyorRequest / PauseTunnel                                                                             |
| `POST /HotDollyOn`                               | Coil on                                                                             | Snap7 send roller                                                                                                    |
| `POST /HotDollyOff`                              | Coil off                                                                            | **400** unsupported (no PLC equivalent)                                                                              |
| `POST /sendWash`                                 | Optional `WASH_MAP` / `WASH_MAP_CONTROLLER_TO_POS`; response `WashPackage` / lists  | `REVERSE_WASH_MAP`; BaseWash **1–20**, Upsell/Override **1–10**; same response keys. Stacker disabled → JSON **500** |
| `GET /GetWashCounts`                             | Length-16 raw; zero-padded parsed; `midnight_local`; **501** if no DTD (e.g. C6000) | Washes 21, Upsells/Overrides **10**; zero-padded parsed; `controller_lifetime`                                       |
| `GET /ping_controller`                           | `online`, `site_code`, `controller_version_number`                                  | `online`, null site/version, plus `system_status`                                                                    |
| Vehicle / arch / stall / asset map / output sync | Yes                                                                                 | **404**                                                                                                              |
| `/washlink/*` diagnostics                        | **404**                                                                             | Gated by `DIAGNOSTIC_MODE`                                                                                           |

## Wash maps and ranges

### MCWW

`/sendWash` body codes are whatever the POS sends. Define translation with **exactly one** of:

* `WASH_MAP` — POS → controller
* `WASH_MAP_CONTROLLER_TO_POS` — controller → POS (inverted at startup)

Omit both (or set `{}`) for direct writes. When a map is active: POS key hit → mapped value; else in-range controller codes that are not reserved map targets are accepted as raw fallback.

Verify live ranges with `GET /get_controller_version` (`BaseWash_*`, `Upsell_*`, `Override_*`). Series bands include C1000, C4, C5000, C6000, and **C7000** (New in 2.4).

### Washlink (New in 2.4 response parity)

Uses `REVERSE_WASH_MAP` (no raw fallback). Body ranges: BaseWash **1–20**; UpsellList / OverrideList **1–10**. Success JSON matches MCWW: `WashPackage`, `UpsellList`, `OverrideList`.

## Wash counts (New in 2.4)

`GET /GetWashCounts` returns wash / upsell / override tallies:

```json
{
  "raw": { "Washes": [], "Upsells": [], "Overrides": [] },
  "parsed": {
    "Washes": { "Wash_01": 0 },
    "Upsells": { "Upsell_01": 0 },
    "Overrides": { "Override_01": 0 }
  },
  "reset_policy": "midnight_local | controller_lifetime"
}
```

Both modes use **2-digit zero-padded** `parsed` keys so lexicographic order matches numeric order.

## Authentication

Closed LAN only. No request authentication. CORS allows all origins for LAN browser clients — do not expose to the public internet.

## Error Handling

Handled domain failures return JSON:

```json
{ "message": "...", "error": "optional_code" }
```

Common status codes:

* **200** — Success (endpoint-specific body)
* **400** — Client / domain error (`WashError`, validation, unsupported)
* **403** — Diagnostic mode disabled
* **404** — Endpoint not available in the active controller mode
* **500** — Internal error or deprecated conveyor stubs
* **501** — Wash counts not configured for this MCWW series