FreeDMR/docs/api.md

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:

[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

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

Version

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

Get Options

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:

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

Set Options

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

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

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

Stop FreeDMR

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