# FreeDMR API

FreeDMR includes an experimental HTTP/JSON API for small live control-plane
actions. It is intended for local administration and automation, not for public
internet exposure.

Enable it with:

```ini
[GLOBAL]
ENABLE_API: True
```

When enabled, the API listens on TCP port `8000`.

## Safety Notes

FreeDMR is a live voice routing process. API requests are deliberately limited
to small in-memory operations so they do not delay DMR voice packet handling.
Request bodies larger than 8192 bytes are rejected.

Bind or firewall port `8000` appropriately. Do not expose it publicly without a
trusted reverse proxy and access controls.

## Authentication

User-level endpoints require:

- `dmrid`: the connected HBP peer/repeater DMR ID
- `key`: the session options key for that peer

System-level endpoints require:

- `systemkey`: the FreeDMR system API key

## Endpoints

### Health

```bash
curl http://127.0.0.1:8000/api/v1/health
```

### Version

```bash
curl http://127.0.0.1:8000/api/v1/version
```

### Get Options

```bash
curl -X POST http://127.0.0.1:8000/api/v1/options/get \
  -H 'content-type: application/json' \
  -d '{"dmrid":1234567,"key":"secret"}'
```

If no live options are present, the response is:

```json
{"ok":true,"connected":true,"has_options":false,"options":""}
```

### Set Options

```bash
curl -X POST http://127.0.0.1:8000/api/v1/options/set \
  -H 'content-type: application/json' \
  -d '{"dmrid":1234567,"key":"secret","options":"KEY=secret;TS1=91;DIAL=2350"}'
```

The `options` value must be the complete FreeDMR `OPTIONS` string. The API does
not add or preserve `KEY=...` automatically.

### Reset Peer Session

```bash
curl -X POST http://127.0.0.1:8000/api/v1/reset \
  -H 'content-type: application/json' \
  -d '{"dmrid":1234567,"key":"secret"}'
```

FreeDMR expects one HBP peer per master instance, so this resets the master
instance that owns the authenticated peer session.

### Reset All Connections

```bash
curl -X POST http://127.0.0.1:8000/api/v1/system/resetall \
  -H 'content-type: application/json' \
  -d '{"systemkey":"system-secret"}'
```

### Stop FreeDMR

```bash
curl -X POST http://127.0.0.1:8000/api/v1/system/kill \
  -H 'content-type: application/json' \
  -d '{"systemkey":"system-secret"}'
```

## Responses

Successful responses include `"ok": true`. Failed responses include
`"ok": false` and an `error` string.

Common errors:

- `invalid_credentials`
- `invalid_json`
- `missing_options`
- `request_too_large`
- `not_found`