Table Of Contents

Previous topic

Contacts

Next topic

Lan

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

Get the current Connection status

GET /api/v3/connection/

Returns the current ConnectionStatus

Example request:

GET /api/v3/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_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/v3/connection/config/

Returns the current ConnectionConfiguration

Example request:

GET /api/v3/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/v3/connection/config/

Updates the ConnectionConfiguration

Example request:

PUT /api/v3/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/v3/connection/ipv6/config/

Returns the current ConnectionIpv6Configuration

Example request:

GET /api/v3/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/v3/connection/ipv6/config/

Updates the ConnectionIpv6Configuration

Example request:

PUT /api/v3/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/v3/connection/xdsl/

Returns the current XdslInfos

Example request:

GET /api/v3/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
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/v3/connection/ftth/

Returns the current FtthStatus

Example request:

GET /api/v3/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/v3/connection/ddns/{provider}/status/

Returns the current DDNSStatus

Example request:

GET /api/v3/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/v3/connection/ddns/{provider}/

Returns the current DDNSConfig

Example request:

GET /api/v3/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/v3/connection/ddns/{provider}/

Set the DDNSConfig

Example request:

PUT /api/v3/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"
    }

}