# REST & WebSocket API (OpenAPI 3.1 stub)

> A proposed HTTP/JSON face for the loudspeakers, served by the cabinet or a small gateway, described in OpenAPI so an assistant can generate a client from it.
>
> Status: draft-spec. Canonical: https://www.edcacoustics.com/developers/api/

> **Status: proposal.** Endpoint shapes are proposals; transport, port and authentication are placeholders. The stub is published so developers and EDC's engineers can react to something concrete. Download: [`/developers/openapi.yaml`](/developers/openapi.yaml).

## Eight core endpoints

| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/devices` | Discover devices on the local network |
| GET | `/v1/devices/{id}` | Identity, model, firmware, network |
| GET | `/v1/devices/{id}/status` | Telemetry: transducer, thermal and amplifier faults; input levels |
| GET / PUT | `/v1/devices/{id}/beams/{n}` | Beam 1–4 aim, shape, level, delay, source input (`?apply=true`) |
| PUT | `/v1/devices/{id}/inputs/{n}` | Gain, mute, 8-band EQ, compressor (inputs 1–3) |
| GET | `/v1/presets` | Coverage presets (device or whole array) |
| POST | `/v1/presets/{id}/recall` | Recall on one device or an array |
| GET | `/v1/events` | WebSocket upgrade — telemetry and state-change stream |

## Beam schema (excerpt)

```yaml
Beam:
  type: object
  properties:
    enabled:      { type: boolean }
    pan_deg:      { type: number, minimum: -60, maximum: 60 }   # A&E spec: ±60°
    tilt_deg:     { type: number, minimum: -60, maximum: 60 }
    h_width_deg:  { type: number, minimum: 2,   maximum: 120 }  # datasheet says 1°; reconcile
    v_width_deg:  { type: number, minimum: 2,   maximum: 120 }
    h_skew_db_per_deg: { type: number }
    v_skew_db_per_deg: { type: number }
    level_db:     { type: number }
    delay_ms:     { type: number }
    input:        { type: integer, minimum: 1, maximum: 3 }
```

Ranges mirror what EDC's A&E specification and iOS guide already state: four beams, three inputs, eight EQ bands, ±60° pan and tilt, 2°–120° widths. Everything else is a placeholder.

## Try it

The API will be served by the [device simulator](/developers/simulator/) so every example on these pages can be run without hardware.