Connection API¶

This API provides Freebox connection settings information.

Connection Errors¶

When attempting to access the file connection API, you may encounter the following errors:

error_code	Description
inval	invalid request
nodev	no device found with this name
noent	no entity found with this name
netdown	network is down
busy	device is busy
invalid_port	invalid port
insecure_password	the password is too weak to enable remote access
invalid_provider	invalid ddns provider name
invalid_next_hop	invalid next hop address (should be a link local address)

Connection status¶

Connection status object¶

ConnectionStatus¶

state enum Read-only¶

State	Description
going_up	connection is initializing
up	connection is active
going_down	connection is about to become inactive
down	connection is inactive

type enum Read-only¶

Type	Description
ethernet	FTTH
rfc2684	xDSL (unbundled)
pppoatm	xDSL

media enum Read-only¶

Media	Description
ftth	FTTH
xdsl	xDSL

ipv4 string Read-only¶

Freebox IPv4 address

NOTE: this field is only available when connection state is up

ipv6 string Read-only¶

Freebox IPv6 address

NOTE: this field is only available when connection state is up

rate_up int Read-only¶: current upload rate in byte/s

rate_down int Read-only¶: current download rate in byte/s

bandwidth_up int Read-only¶: available upload bandwidth in bit/s

bandwidth_down int Read-only¶: available download bandwidth in bit/s

bytes_up int Read-only¶: total uploaded bytes since last connection

bytes_down int Read-only¶: total downloaded bytes since last connection

ipv4_port_range int[2] Read-only¶

Some customers share the same IPv4 and each customer is then assigned a port range. The first value is the first port of the assigned range and the second value is the last port (inclusive).

All PortForwardingConfig must use ports in this range to be effective.

Get the current Connection status¶

GET /api/v4/connection/¶

Returns the current ConnectionStatus

Example request:

GET /api/v4/connection/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "type": "ethernet",
        "rate_down": 61,
        "bytes_up": 5489542,
        "rate_up": 0,
        "bandwidth_up": 100000000,
        "ipv4": "13.37.42.42",
        "ipv6": "2a01:e30:d252:a2a0::1",
        "bandwidth_down": 100000000,
        "state": "up",
        "bytes_down": 13332830,
        "media": "ftth"
    }
}

Connection configuration¶

Connection configuration object¶

ConnectionConfiguration¶

ping bool¶: should the Freebox respond to external ping requests

is_secure_pass bool Read-only¶: is the admin password secure enough to enable remote access

remote_access bool¶: enable/disable HTTP remote access

remote_access_port int¶: port number to use for remote HTTP access

remote_access_min_port int Read-only¶: This field indicate the minimum possible value for remote_access_port (see ConnectionStatus ipv4_port_range)

remote_access_max_port int Read-only¶: This field indicate the maximum possible value for remote_access_port (see ConnectionStatus ipv4_port_range)

remote_access_ip string Read-only¶: IPv4 to use for remote access (can be missing if connection is down)

api_remote_access bool Read-only¶: is remote access enabled for apps, or share link

wol bool¶: enable/disable Wake-on-lan proxy

adblock bool¶: is ads blocking feature enabled

adblock_not_set bool Read-only¶: if set to true adblock setting has never been set by the user

allow_token_request bool¶: if false, user has disabled new token request. New apps can’t request a new token. Apps that already have a token are still allowed

Get the current Connection configuration¶

GET /api/v4/connection/config/¶

Returns the current ConnectionConfiguration

Example request:

GET /api/v4/connection/config/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "ping": true,
        "is_secure_pass": false,
        "remote_access_port": 80,
        "remote_access": false,
        "wol": false,
        "adblock": false,
        "adblock_not_set": false,
        "api_remote_access": true,
        "allow_token_request": true,
        "remote_access_ip": "312.13.37.42"
    }
}

Update the Connection configuration¶

PUT /api/v4/connection/config/¶

Updates the ConnectionConfiguration

Example request:

PUT /api/v4/connection/config/ HTTP/1.1
Host: mafreebox.freebox.fr

{
  "ping": true,
  "wol": false
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "ping": true,
        "is_secure_pass": false,
        "remote_access_port": 80,
        "remote_access": false,
        "wol": false,
        "adblock": false,
        "adblock_not_set": false,
        "api_remote_access": true,
        "allow_token_request": true,
        "remote_access_ip": "312.13.37.42"
    }
}

Connection IPv6 configuration¶

Connection IPv6 configuration object¶

ConnectionIpv6Delegation¶

prefix string¶: IPv6 prefix

next_hop ipv6¶: the next hop for the prefix

ConnectionIpv6Configuration¶

ipv6_enabled bool¶: is IPv6 enabled

ipv6ll string Read-only¶: Freebox IPv6 link local address

delegations ConnectionIpv6Delegation[8]¶: list of IPv6 delegations

Get the current IPv6 Connection configuration¶

GET /api/v4/connection/ipv6/config/¶

Returns the current ConnectionIpv6Configuration

Example request:

GET /api/v4/connection/ipv6/config/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "ipv6_enabled": true,
        "delegations": [
            {
                "prefix": "2a01:e30:d252:a2a0::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a1::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a2::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a3::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a4::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a5::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a6::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a7::/64",
                "next_hop": ""
            }
        ]
    }
}

Update the IPv6 Connection configuration¶

PUT /api/v4/connection/ipv6/config/¶

Updates the ConnectionIpv6Configuration

Example request:

PUT /api/v4/connection/config/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "delegations": [
      {
         "prefix": "2a01:e30:d252:a2a2::/64",
         "next_hop": "fe80::be30:5bff:feb5:fcc7"
      }
   ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "ipv6_enabled": true,
        "ipv6ll": "fe80::224:d4ff:acac:ecec",
        "delegations": [
            {
                "prefix": "2a01:e30:d252:a2a0::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a1::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a2::/64",
                "next_hop": "fe80::d252:5bff:feb5:fcc7"
            },
            {
                "prefix": "2a01:e30:d252:a2a3::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a4::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a5::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a6::/64",
                "next_hop": ""
            },
            {
                "prefix": "2a01:e30:d252:a2a7::/64",
                "next_hop": ""
            }
        ]
    }
}

Connection xDSL status [UNSTABLE]¶

xDSL status object [UNSTABLE]¶

XdslStatus¶

status enum Read-only¶

Status	Description
down	unsynchronized
training	synchronizing step 1/4
started	synchronizing step 2/4
chan_analysis	synchronizing step 3/4
msg_exchange	synchronizing step 4/4
showtime	Ready
disabled	Disabled

protocol enum Read-only¶

Protocol	Description
t1413	T1.413
adsl1_a	ADSL
adsl2_a	ADSL2
adsl2plus_a	ADSL2+
readsl2	ReachDSL
adsl2_m	ADSL2 annex M
adsl2plus_m	ADSL2+ annex M
unknown	Unknown

modulation enum Read-only¶

Protocol	Description
adsl	ADSL
vdsl	VDSL

uptime int Read-only¶: uptime in seconds

xDSL stats object [UNSTABLE]¶

XdslStats¶

maxrate int Read-only¶: ATM max rate in kbit/s

rate int Read-only¶: ATM rate in kbit/s

snr int Read-only¶: in dB

attn int Read-only¶: in dB

snr_10 int Read-only¶: in dB/10

attn_10 int Read-only¶: in dB/10

fec int Read-only¶

crc int Read-only¶

hec int Read-only¶

es int Read-only¶

ses int Read-only¶

phyr bool Read-only¶

ginp bool Read-only¶

nitro bool Read-only¶

rxmt int Read-only¶: only available when phyr is on

rxmt_corr int Read-only¶: only available when phyr is on

rxmt_uncorr int Read-only¶: only available when phyr is on

rtx_tx int Read-only¶: only available when ginp is on

rtx_c int Read-only¶: only available when ginp is on

rtx_uc int Read-only¶: only available when ginp is on

xDSL infos object [UNSTABLE]¶

XdslInfos¶

status XdslStatus ¶

down XdslStats ¶

up XdslStats ¶

Get the current xDSL infos¶

GET /api/v4/connection/xdsl/¶

Returns the current XdslInfos

Example request:

GET /api/v4/connection/xdsl/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "status": {
            "status": "showtime",
            "protocol": "adsl2plus_a",
            "uptime": 5017,
            "modulation": "adsl"
        },
        "down": {
            "es": 43,
            "phyr": true,
            "attn": 0,
            "snr": 7,
            "nitro": true,
            "rate": 28031,
            "hec": 0,
            "crc": 0,
            "rxmt_uncorr": 0,
            "rxmt_corr": 0,
            "ses": 43,
            "fec": 0,
            "maxrate": 30636,
            "rxmt": 0
        },
        "up": {
            "es": 0,
            "phyr": false,
            "attn": 23,
            "snr": 15,
            "nitro": true,
            "rate": 1022,
            "hec": 0,
            "crc": 0,
            "rxmt_uncorr": 0,
            "rxmt_corr": 0,
            "ses": 0,
            "fec": 0,
            "maxrate": 1022,
            "rxmt": 0
        }
    }

}

Connection FTTH status [UNSTABLE]¶

FTTH status object [UNSTABLE]¶

FtthStatus¶

sfp_present boolean Read-only¶

sfp_alim_ok boolean Read-only¶

sfp_has_power_report boolean Read-only¶

sfp_has_signal boolean Read-only¶

link boolean Read-only¶

sfp_serial string Read-only¶

sfp_model string Read-only¶

sfp_vendor string Read-only¶

sfp_vendor string Read-only

sfp_pwr_tx int Read-only¶: scaled by 100 (in dBm)

sfp_pwr_rx int Read-only¶: scaled by 100 (in dBm)

Get the current FTTH status¶

GET /api/v4/connection/ftth/¶

Returns the current FtthStatus

Example request:

GET /api/v4/connection/ftth/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "sfp_has_power_report": true,
        "sfp_has_signal": false,
        "sfp_model": "SPBD-1250E4H2RDB",
        "sfp_vendor": "DELTA",
        "sfp_pwr_tx": -1172,
        "sfp_pwr_rx": -3698,
        "link": false,
        "sfp_alim_ok": true,
        "sfp_serial": "DE104900000471",
        "sfp_present": true
    }
}

Connection DynDNS status¶

DynDnsProvider status object¶

DDNSStatus¶

status enum¶

Status	Description
disabled	Disabled
ok	Ok
wait	Updating
reqfail	Request failed
authfail	Authentication error
nocredential	Invalid credential
ipinval	Invalid IP
hostinval	Invalid hostname
abuse	Blocked because of abuse
dnserror	DNS error
unavailable	Service unavailable
nowan	Unable to get wan IP
unknown	Unknown

next_refresh int¶: next refresh timestamp

last_refresh int¶: last refresh timestamp

next_retry int¶: next retry timestamp

last_error int¶: last error timestamp

Get the status of a DynDNS service¶

Right now the supported dynamic dns providers are:

ovh
dyndns
noip

GET /api/v4/connection/ddns/{provider}/status/¶

Returns the current DDNSStatus

Example request:

GET /api/v4/connection/ddns/dyndns/status/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{

    "success": true,
    "result": {
        "last_error": 1354127350,
        "status": "hostinval",
        "next_refresh": 0,
        "last_refresh": 0,
        "next_retry": 0
    }

}

Connection DynDNS configuration¶

DynDns config object¶

DDNSConfig¶

enabled bool¶

hostname string¶: dns name to use to register

password string Write-only¶: password to use to register

user string¶: username to use to register

Get the config of a DynDNS service¶

GET /api/v4/connection/ddns/{provider}/¶

Returns the current DDNSConfig

Example request:

GET /api/v4/connection/ddns/dyndns/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{

    "success": true,
    "result": {
        "enabled": true,
        "hostname": "test",
        "user": "test"
    }

}

Set the config of a DynDNS service¶

PUT /api/v4/connection/ddns/{provider}/¶

Set the DDNSConfig

Example request:

PUT /api/v4/connection/ddns/dyndns/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "enabled": false,
   "user": "test",
   "password": "ssss",
   "hostname": "ttt"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{

    "success": true,
    "result": {
        "enabled": false,
        "hostname": "ttt",
        "user": "test"
    }

}