mikrotik-api

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:

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

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

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)

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)

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)

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)

resource.remove(id='*1')

Calling commands (CALL)

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

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

Complete Resource Path Reference

System

Interfaces

IP

Firewall

IPv6

Routing (RouterOS 7)

PPP

Queues (QoS)

CAPsMAN / WiFi Controller (ROS 7)

MPLS

Tools

Container (ROS 7.4+)

IoT

ZeroTier

Advanced Operations

Filtering with multiple parameters

resource = api.get_resource('/ip/firewall/filter')
rules = resource.get(chain='forward', action='drop')

Ordering firewall rules (place-before)

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

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

Batch operations

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

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

Get specific properties only

# 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)

# 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

# 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

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

Firmware / Package update

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

# 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

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

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

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

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).