mikrotik-api

---
name: mikrotik-api
description: "Manages MikroTik routers via the RouterOS API (port 8728/8729). Use when the user wants to configure, monitor, or troubleshoot a MikroTik router — including interfaces, firewall, DHCP, DNS, routing, queues, VPN, and system management."
---

# MikroTik API Management

Communicate with MikroTik RouterOS devices using the Python `routeros-api` library over the API port (8728 plain, 8729 SSL).

## Prerequisites

Install the library if not present:
```bash
pip3 install --break-system-packages routeros-api
```

## Connection

It is highly recommended to use environment variables for credentials to avoid hardcoding.

### Environment Variables
Set these in your environment or `.env` file:
- `MIKROTIK_HOST`: Router IP or hostname
- `MIKROTIK_USERNAME`: Router username
- `MIKROTIK_PASSWORD`: Router password

### Python Connection Pattern
```python
import routeros_api
import os

# Get credentials from environment variables
host = os.getenv('MIKROTIK_HOST')
username = os.getenv('MIKROTIK_USERNAME')
password = os.getenv('MIKROTIK_PASSWORD')

# Fallback to manual input if env vars are missing
if not all([host, username, password]):
    print("Environment variables MIKROTIK_HOST, MIKROTIK_USERNAME, or MIKROTIK_PASSWORD are not set.")
    # host = input("Enter Host: ") ...

conn = routeros_api.RouterOsApiPool(
    host=host,
    username=username,
    password=password,
    plaintext_login=True,   # Required for RouterOS 6.43+
    port=8728               # Use 8729 for SSL
)
api = conn.get_api()
# ... do work ...
conn.disconnect()
```

### Connection Rules
- **Prefer Environment Variables**: Instruct the user to set `MIKROTIK_HOST`, `MIKROTIK_USERNAME`, and `MIKROTIK_PASSWORD`.
- Ask the user for these details only if not found in the environment.
- Default API port is **8728** (plain) or **8729** (SSL).
- Always call `conn.disconnect()` when done.
- Use `plaintext_login=True` for RouterOS v6.43+ and v7.x.

### SSL Connection
```python
conn = routeros_api.RouterOsApiPool(
    host=host,
    username=username,
    password=password,
    plaintext_login=True,
    use_ssl=True,
    ssl_verify=False,       # Set True with proper certs
    ssl_verify_hostname=False,
    port=8729
)
```

## Core API Operations

### Reading resources (GET / print)
```python
resource = api.get_resource('/ip/address')
items = resource.get()                          # Get all
items = resource.get(interface='ether1')         # Filter by param
items = resource.get(disabled='false')           # Filter by status
```

### Adding entries (ADD)
```python
resource = api.get_resource('/ip/address')
resource.add(address='192.168.1.1/24', interface='ether1')
# With comment
resource.add(address='192.168.1.1/24', interface='ether1', comment='Management')
```

### Updating entries (SET)
```python
resource = api.get_resource('/ip/address')
resource.set(id='*1', address='192.168.2.1/24')
resource.set(id='*1', comment='Updated via API')
resource.set(id='*1', disabled='yes')           # Disable entry
resource.set(id='*1', disabled='no')            # Enable entry
```

### Removing entries (REMOVE)
```python\nresource = api.get_resource('/ip/address')
resource.remove(id='*1')
```

### Calling commands (CALL)
```python
resource = api.get_resource('/system')
resource.call('reboot')

# Call with parameters
resource = api.get_resource('/ip/firewall/filter')
resource.call('move', {'numbers': '*1', 'destination': '*5'})
```

### Enabling / Disabling entries
```python
resource = api.get_resource('/interface')
resource.set(id='*1', disabled='yes')   # Disable
resource.set(id='*1', disabled='no')    # Enable
```

## Complete Resource Path Reference

### System
| Task | Resource Path |
|------|--------------|
| System info (CPU, RAM, uptime) | `/system/resource` |
| Router identity | `/system/identity` |
| System clock | `/system/clock` |
| NTP client | `/system/ntp/client` |
| NTP server | `/system/ntp/server` |
| Scheduler | `/system/scheduler` |
| Scripts | `/system/script` |
| Logging rules | `/system/logging` |
| Log entries | `/log` |
| Packages | `/system/package` |
| Package update | `/system/package/update` |
| Router board info | `/system/routerboard` |
| License | `/system/license` |
| Health (voltage, temp) | `/system/health` |
| History | `/system/history` |
| Users | `/user` |
| User groups | `/user/group` |
| Active users | `/user/active` |
| SSH keys | `/user/ssh-keys` |
| Files | `/file` |
| Backup | `/system/backup` |
| SNMP | `/snmp` |
| SNMP community | `/snmp/community` |
| Certificates | `/certificate` |
| Console | `/system/console` |
| LEDs | `/system/leds` |

### Interfaces
| Task | Resource Path |
|------|--------------|
| All interfaces | `/interface` |
| Ethernet | `/interface/ethernet` |
| Bridge | `/interface/bridge` |
| Bridge ports | `/interface/bridge/port` |
| Bridge VLANs | `/interface/bridge/vlan` |
| Bridge hosts (MAC table) | `/interface/bridge/host` |
| Bridge MSTi | `/interface/bridge/msti` |
| Bridge settings | `/interface/bridge/settings` |
| VLAN | `/interface/vlan` |
| Bonding (LACP/bonding) | `/interface/bonding` |
| EoIP tunnel | `/interface/eoip` |
| GRE tunnel | `/interface/gre` |
| IPIP tunnel | `/interface/ipip` |
| VXLAN | `/interface/vxlan` |
| VXLAN VTEP | `/interface/vxlan/vtep` |
| WireGuard | `/interface/wireguard` |
| WireGuard peers | `/interface/wireguard/peers` |
| L2TP client | `/interface/l2tp-client` |
| L2TP server | `/interface/l2tp-server/server` |
| SSTP client | `/interface/sstp-client` |
| SSTP server | `/interface/sstp-server/server` |
| OVPN client | `/interface/ovpn-client` |
| OVPN server | `/interface/ovpn-server/server` |
| PPPoE client | `/interface/pppoe-client` |
| PPPoE server | `/interface/pppoe-server/server` |
| PPTP client | `/interface/pptp-client` |
| PPTP server | `/interface/pptp-server/server` |
| LTE | `/interface/lte` |
| LTE APN | `/interface/lte/apn` |
| Wireless (WiFi legacy) | `/interface/wireless` |
| WiFi (new, ROS 7) | `/interface/wifi` |
| WiFi channels | `/interface/wifi/channel` |
| WiFi datapath | `/interface/wifi/datapath` |
| WiFi security | `/interface/wifi/security` |
| WiFi configuration | `/interface/wifi/configuration` |
| WiFi provisioning | `/interface/wifi/provisioning` |
| WiFi registration table | `/interface/wifi/registration-table` |
| WiFi access list | `/interface/wifi/access-list` |
| WiFi interworking | `/interface/wifi/interworking` |
| Interface lists | `/interface/list` |
| Interface list members | `/interface/list/member` |
| Ethernet switch | `/interface/ethernet/switch` |
| Ethernet switch port | `/interface/ethernet/switch/port` |
| Traffic monitor | `/interface/monitor-traffic` |

### IP
| Task | Resource Path |
|------|--------------|
| IP addresses | `/ip/address` |
| ARP table | `/ip/arp` |
| Routes | `/ip/route` |
| Route rules | `/ip/route/rule` |
| DNS settings | `/ip/dns` |
| DNS static entries | `/ip/dns/static` |
| DNS cache | `/ip/dns/cache` |
| DHCP client | `/ip/dhcp-client` |
| DHCP server | `/ip/dhcp-server` |
| DHCP server network | `/ip/dhcp-server/network` |
| DHCP server leases | `/ip/dhcp-server/lease` |
| DHCP server option | `/ip/dhcp-server/option` |
| DHCP server option sets | `/ip/dhcp-server/option/sets` |
| DHCP relay | `/ip/dhcp-relay` |
| IP pool | `/ip/pool` |
| IP neighbors | `/ip/neighbor` |
| IP neighbor discovery | `/ip/neighbor/discovery-settings` |
| IP services | `/ip/service` |
| IP settings (forwarding) | `/ip/settings` |
| IP proxy | `/ip/proxy` |
| IP proxy access list | `/ip/proxy/access` |
| IP SOCKS | `/ip/socks` |
| IP SSH | `/ip/ssh` |
| IP cloud | `/ip/cloud` |
| IP UPnP | `/ip/upnp` |
| IP UPnP interfaces | `/ip/upnp/interfaces` |
| IP SMB | `/ip/smb` |
| IP traffic flow | `/ip/traffic-flow` |
| IP traffic flow target | `/ip/traffic-flow/target` |
| IP accounting | `/ip/accounting` |
| IP Kid Control | `/ip/kid-control` |
| IP Kid Control devices | `/ip/kid-control/device` |
| IP Hotspot | `/ip/hotspot` |
| IP Hotspot profile | `/ip/hotspot/profile` |
| IP Hotspot user | `/ip/hotspot/user` |
| IP Hotspot user profile | `/ip/hotspot/user/profile` |
| IP Hotspot active | `/ip/hotspot/active` |
| IP Hotspot host | `/ip/hotspot/host` |
| IP Hotspot cookie | `/ip/hotspot/cookie` |
| IP Hotspot IP binding | `/ip/hotspot/ip-binding` |
| IP Hotspot walled garden | `/ip/hotspot/walled-garden` |
| IP Hotspot walled garden IP | `/ip/hotspot/walled-garden/ip` |

### Firewall
| Task | Resource Path |
|------|--------------|
| Filter rules | `/ip/firewall/filter` |
| NAT rules | `/ip/firewall/nat` |
| Mangle rules | `/ip/firewall/mangle` |
| RAW rules | `/ip/firewall/raw` |
| Address lists | `/ip/firewall/address-list` |
| Connections (conntrack) | `/ip/firewall/connection` |
| Connection tracking | `/ip/firewall/connection/tracking` |
| Service ports (ALGs) | `/ip/firewall/service-port` |
| Layer 7 protocols | `/ip/firewall/layer7-protocol` |

### IPv6
| Task | Resource Path |
|------|--------------|
| IPv6 addresses | `/ipv6/address` |
| IPv6 routes | `/ipv6/route` |
| IPv6 firewall filter | `/ipv6/firewall/filter` |
| IPv6 firewall mangle | `/ipv6/firewall/mangle` |
| IPv6 firewall RAW | `/ipv6/firewall/raw` |
| IPv6 firewall address list | `/ipv6/firewall/address-list` |
| IPv6 ND (Neighbor Disc.) | `/ipv6/nd` |
| IPv6 ND prefix | `/ipv6/nd/prefix` |
| IPv6 DHCP client | `/ipv6/dhcp-client` |
| IPv6 DHCP server | `/ipv6/dhcp-server` |
| IPv6 pool | `/ipv6/pool` |
| IPv6 settings | `/ipv6/settings` |

### Routing (RouterOS 7)
| Task | Resource Path |
|------|--------------|
| Routing tables | `/routing/table` |
| Routing rules | `/routing/rule` |
| OSPF instance | `/routing/ospf/instance` |
| OSPF area | `/routing/ospf/area` |
| OSPF interface template | `/routing/ospf/interface-template` |
| OSPF neighbors | `/routing/ospf/neighbor` |
| OSPF LSA | `/routing/ospf/lsa` |
| BGP connection | `/routing/bgp/connection` |
| BGP template | `/routing/bgp/template` |
| BGP session | `/routing/bgp/session` |
| BGP advertisements | `/routing/bgp/advertisements` |
| BGP networks | `/routing/bgp/network` |
| RIP instance | `/routing/rip/instance` |
| RIP interface template | `/routing/rip/interface-template` |
| Route filter rules | `/routing/filter/rule` |
| Route filter select rules | `/routing/filter/select-rule` |
| Prefix lists | `/routing/filter/community-list` |
| BFD session | `/routing/bfd/session` |
| BFD configuration | `/routing/bfd/configuration` |
| Routing ID | `/routing/id` |
| RPKI | `/routing/rpki` |
| IGMP Proxy | `/routing/igmp-proxy` |
| PIM | `/routing/pimsm` |

### PPP
| Task | Resource Path |
|------|--------------|
| PPP secrets | `/ppp/secret` |
| PPP profiles | `/ppp/profile` |
| PPP active connections | `/ppp/active` |
| PPP AAA settings | `/ppp/aaa` |
| PPP L2TP secret | `/ppp/l2tp-secret` |

### Queues (QoS)
| Task | Resource Path |
|------|--------------|
| Simple queues | `/queue/simple` |
| Queue tree | `/queue/tree` |
| Queue types | `/queue/type` |
| Interface queues | `/queue/interface` |

### CAPsMAN / WiFi Controller (ROS 7)
| Task | Resource Path |
|------|--------------|
| CAPsMAN manager | `/caps-man/manager` |
| CAPsMAN configuration | `/caps-man/configuration` |
| CAPsMAN channel | `/caps-man/channel` |
| CAPsMAN datapath | `/caps-man/datapath` |
| CAPsMAN security | `/caps-man/security` |
| CAPsMAN provisioning | `/caps-man/provisioning` |
| CAPsMAN interface | `/caps-man/interface` |
| CAPsMAN registration table | `/caps-man/registration-table` |
| CAPsMAN access list | `/caps-man/access-list` |
| CAPsMAN remote-cap | `/caps-man/remote-cap` |

### MPLS
| Task | Resource Path |
|------|--------------|
| MPLS settings | `/mpls` |
| MPLS interface | `/mpls/interface` |
| MPLS forwarding table | `/mpls/forwarding-table` |
| MPLS LDP | `/mpls/ldp` |
| MPLS LDP interface | `/mpls/ldp/interface` |
| MPLS LDP neighbor | `/mpls/ldp/neighbor` |
| VPLS | `/interface/vpls` |
| Traffic engineering | `/mpls/traffic-eng` |

### Tools
| Task | Resource Path |
|------|--------------|
| Ping | `/tool/ping` (use `call`) |
| Traceroute | `/tool/traceroute` (use `call`) |
| Bandwidth test | `/tool/bandwidth-test` (use `call`) |
| Torch (traffic by IP) | `/tool/torch` (use `call`) |
| Profile (CPU profile) | `/tool/profile` |
| Netwatch | `/tool/netwatch` |
| E-mail settings | `/tool/e-mail` |
| Fetch (HTTP client) | `/tool/fetch` |
| Graphing interface | `/tool/graphing/interface` |
| Graphing resource | `/tool/graphing/resource` |
| Graphing queue | `/tool/graphing/queue` |
| Sniffer | `/tool/sniffer` |
| SNMP | `/snmp` |
| MAC server | `/tool/mac-server` |
| MAC Winbox | `/tool/mac-server/mac-winbox` |
| MAC Ping | `/tool/mac-server/ping` |
| Bandwidth server | `/tool/bandwidth-server` |
| IP Scan | `/tool/ip-scan` |
| SMS | `/tool/sms` |
| Romon | `/tool/romon` |

### Container (ROS 7.4+)
| Task | Resource Path |
|------|--------------|
| Container config | `/container/config` |
| Containers | `/container` |
| Container mounts | `/container/mounts` |
| Container envs | `/container/envs` |

### IoT
| Task | Resource Path |
|------|--------------|
| IoT Bluetooth | `/iot/bluetooth` |
| IoT Bluetooth scanners | `/iot/bluetooth/scanners` |
| IoT GPIO | `/iot/gpio` |
| IoT MQTT broker | `/iot/mqtt/brokers` |

### ZeroTier
| Task | Resource Path |
|------|--------------|
| ZeroTier | `/zerotier` |
| ZeroTier interface | `/zerotier/interface` |

## Advanced Operations

### Filtering with multiple parameters
```python
resource = api.get_resource('/ip/firewall/filter')
rules = resource.get(chain='forward', action='drop')
```

### Ordering firewall rules (place-before)
```python
resource = api.get_resource('/ip/firewall/filter')
resource.add(
    chain='forward',
    action='accept',
    src_address='10.0.0.0/8',
    place_before='*5'       # Insert before rule *5
)
```
Note: Use underscores in Python for hyphenated attributes (e.g., `src-address` → `src_address`, `place-before` → `place_before`).

### Moving firewall rules
```python
resource = api.get_resource('/ip/firewall/filter')
resource.call('move', {'numbers': '*A', 'destination': '*1'})
```

### Batch operations
```python
resource = api.get_resource('/ip/firewall/address-list')
ips = ['1.2.3.4', '5.6.7.8', '9.10.11.12']
for ip in ips:
    resource.add(list='blocklist', address=ip, comment='Blocked via API')
```

### Enable/disable by name
```python
resource = api.get_resource('/interface')
ifaces = resource.get(name='ether5')
if ifaces:
    resource.set(id=ifaces[0]['id'], disabled='yes')
```

### Get specific properties only
```python
# The library always returns all properties; filter in Python:
resource = api.get_resource('/interface')
for iface in resource.get():
    print(iface.get('name'), iface.get('type'), iface.get('running'))
```

### Run system tools (ping, traceroute)
```python
# Tools that produce output need call() with parameters
resource = api.get_resource('/tool')
# Note: Some tools (ping, traceroute) run indefinitely.
# Use count parameter to limit.
result = resource.call('ping', {'address': '8.8.8.8', 'count': '4'})
for r in result:
    print(r)
```

### Backup & Export
```python
# Create a backup file
resource = api.get_resource('/system/backup')
resource.call('save', {'name': 'api-backup'})

# Export config to file
resource = api.get_resource('/')
resource.call('export', {'file': 'api-export'})
```

### System reboot / shutdown
```python
resource = api.get_resource('/system')
resource.call('reboot')
# resource.call('shutdown')
```

### Firmware / Package update
```python
resource = api.get_resource('/system/package/update')
resource.call('check-for-updates')
result = resource.get()
print(result)
# resource.call('install')   # Install and reboot
```

## REST API (RouterOS 7.1+)

RouterOS 7.1+ also supports a REST API over HTTP/HTTPS. Use when the Python library is unavailable.

### REST via curl
```bash
# GET - Read resources
curl -k -u user:pass https://<IP>/rest/ip/address

# PUT - Create new entry
curl -k -u user:pass -X PUT https://<IP>/rest/ip/address \
  --data '{"address":"192.168.1.1/24","interface":"ether1"}' \
  -H "content-type: application/json"

# PATCH - Update entry
curl -k -u user:pass -X PATCH https://<IP>/rest/ip/address/*1 \
  --data '{"comment":"updated"}' -H "content-type: application/json"

# DELETE - Remove entry
curl -k -u user:pass -X DELETE https://<IP>/rest/ip/address/*1

# POST - Run any command
curl -k -u user:pass -X POST https://<IP>/rest/ip/address/print \
  --data '{"_proplist":["address","interface"]}' \
  -H "content-type: application/json"
```

### REST with query filters
```bash
curl -k -u user:pass -X POST https://<IP>/rest/interface/print \
  --data '{".query":["type=ether"],"_proplist":["name","type","running"]}' \
  -H "content-type: application/json"
```

### REST via Python requests
```python
import requests
from requests.auth import HTTPBasicAuth

base = 'https://<IP>/rest'
auth = HTTPBasicAuth('<USER>', '<PASS>')

# GET all interfaces
r = requests.get(f'{base}/interface', auth=auth, verify=False)
print(r.json())

# POST (run commands with parameters)
r = requests.post(f'{base}/ip/address/print',
    auth=auth, verify=False,
    json={'_proplist': ['address', 'interface']})
print(r.json())
```

## Error Handling

```python
import routeros_api
from routeros_api.exceptions import RouterOsApiCommunicationError

try:
    conn = routeros_api.RouterOsApiPool(host, username=user, password=pw, plaintext_login=True)
    api = conn.get_api()
    resource = api.get_resource('/ip/address')
    resource.add(address='invalid', interface='nonexistent')
except RouterOsApiCommunicationError as e:
    print(f"API Error: {e}")
except ConnectionError:
    print("Cannot reach router")
finally:
    try:
        conn.disconnect()
    except:
        pass
```

### API Error Categories
| Code | Meaning |
|------|---------|
| 0 | Missing item or command |
| 1 | Argument value failure |
| 2 | Command interrupted |
| 3 | Scripting related failure |
| 4 | General failure |
| 5 | API related failure |
| 6 | TTY related failure |
| 7 | Value from :return command |

## Workflow

1. **Connect** to the router using credentials from environment variables or the user.
2. **Read first** — always fetch current state before making changes.
3. **Confirm** destructive operations (delete, disable, reboot, firewall changes) with the user.
4. **Apply changes** using add/set/remove.
5. **Verify** by reading back the resource after changes.
6. **Disconnect** when done.

## Important Notes

- The `id` field in responses (e.g., `*1`, `*A`) is the internal MikroTik ID used for set/remove.
- Use underscore in Python kwargs for hyphenated RouterOS attributes: `src-address` → `src_address`.
- Filter and NAT rules are **order-sensitive** — use `place_before` when adding to control position.
- Always show the user what currently exists before modifying firewall rules.
- For bulk operations, iterate over results and apply changes one by one.
- RouterOS 7.x uses different paths for routing (e.g., `/routing/ospf/instance` not `/routing/ospf`).
- If the API port is closed, advise the user to enable it: `/ip/service enable api`.
- Tools like ping/traceroute run indefinitely — always pass `count` or `duration` parameter.
- REST API requires `www` or `www-ssl` service enabled on the router.
- REST API has a **60-second timeout** for commands; use limiting params (`count`, `duration`, `once`).