Devices

A device is one set-top box: an account in Ministra, known by its MAC address or a login. It belongs to a subscriber, runs on a tariff plan and is on until its expiry date.

{
  "id": 41,
  "subscriber_id": 7,
  "reseller_id": 3,
  "mac": "00:1A:79:12:34:56",
  "login": null,
  "name": "Living room",
  "enabled": true,
  "tariff_plan": { "id": 2, "name": "Premium 12 months", "months": 12 },
  "expires_at": "2027-10-01T09:12:00Z",
  "expired": false,
  "type": "mag",
  "model": "MAG254",
  "last_active_at": "2026-10-20T18:44:00Z",
  "created_at": "2026-10-01T09:12:00Z"
}

Field
enabled	Switched on. A switched-off box cannot play anything.
expires_at, expired	When the subscription ends, and whether it has. Mintrix switches an expired device off by itself.
type, model	Set when the box first signs in; null until then
last_active_at	When the box was last seen

List

GET /devices

Filter
mac	A MAC address, in any case, with :, - or nothing between: 00-1a-79-12-34-56
login	A login
subscriber_id	One subscriber's devices
enabled	1 switched on, 0 off
expires_before	Expiring before this time or date, e.g. 2026-11-01

Paged: see Lists and paging.

# Devices expiring this month, to remind their customers
curl "https://panel.example.com/api/rest/v1/devices?expires_before=2026-11-01&enabled=1" \
  -H "Authorization: Bearer mtx_your_key"

Read

GET /devices/{id}

Add

POST /devices

Field
subscriber_id	Required	The subscriber it belongs to; it must be one the key may reach
mac	mac or login	The box's MAC address, e.g. 00:1A:79:12:34:56
login	mac or login	For boxes and apps that sign in with a login: letters, digits, _ . @ -
password		With a login, 4 to 64 characters
tariff_plan_id	Required	An active plan: see Tariff plans
name		A label, e.g. Living room

The device runs for the plan's months from now, and the plan's price is charged to the subscriber's account. Send an Idempotency-Key.

curl -X POST https://panel.example.com/api/rest/v1/devices \
  -H "Authorization: Bearer mtx_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-10041" \
  -d '{"subscriber_id": 7, "mac": "00:1A:79:12:34:56", "tariff_plan_id": 2, "name": "Living room"}'

Answers 201 with the device. Refusals: 409 insufficient_credit, device_limit, license_limit, already_exists, 502 ministra_failed. In each case nothing is charged.

Renew

POST /devices/{id}/renew

Field
tariff_plan_id		Another active plan to move the device to. Without it, its current plan.

Adds the plan's months to the expiry date, or to today when it has already passed, and charges the plan's price. Renewing early loses nothing. Send an Idempotency-Key.

curl -X POST https://panel.example.com/api/rest/v1/devices/41/renew \
  -H "Authorization: Bearer mtx_your_key" \
  -H "Idempotency-Key: invoice-10042"

Answers 200 with the device and its new expires_at.

Change

PATCH /devices/{id}

Field
name	A label
enabled	false switches the box off at once, true on again
password	A new password for a login device

The plan and the expiry change only through a renewal.

# The customer stopped paying: switch the box off
curl -X PATCH https://panel.example.com/api/rest/v1/devices/41 \
  -H "Authorization: Bearer mtx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Switching a device on counts against the license's device limit (409 license_limit). An expired device switched on is switched off again within minutes: renew it instead.

Delete

DELETE /devices/{id}

Deletes the device here and in Ministra. Answers 204. Credit already charged is not refunded.