Table Of Contents

Next topic

Api changes from version 1.1 to 2.0

Freebox OS developer API

FreeboxOS Gateway APi allow access to Freebox Server settings and apps.

This API can be used to develop companion apps for Smartphone, or provide an alternative to FreeboxOS web app.

General Information

API Version

Api version will always use the following format : “major.minor” where major and minor are integers

Current API version is “3.0” Current major API version is: 3

When an API is marked as unstable, you can use it but it may change or disappear at any time!

When an API is not documented you should not use it!

Other API will be maintained for at least 1 Freebox release.

Freebox discovery

To discover a Freebox supporting this API you can either use mDNS, or make a HTTP request to mafreebox.freebox.fr to get API information.

Discovery using mDNS

This is the preferred method since it does not require to know the Freebox IP address.

The Freebox broadcasts the “_fbx-api._tcp” service

On iOS devices, you can use a NSNetServiceBrowser

On Android devices, you can use Network Service Discovery or JmDNS

On the TXT record you can obtain the following information:

Key Description
api_version The current API version on the Freebox
device_type “FreeboxServer1,1” for the Freebox Server revision 1,1
api_base_url The API root path on the HTTP server
uid The device unique id

Discovery using HTTP

If you can, avoid this method because it requires to use a hardcoded address to retreive API information.

If you make a HTTP get request on http://mafreebox.freebox.fr/api_version you can get the same API information as provided in mDNS.

Example request:

GET /api_version HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
   uid: "23b86ec8091013d668829fe12791fdab",
   device_name: "Freebox Server",
   api_version: "2.0",
   api_base_url: "/api/",
   device_type: "FreeboxServer1,1"
}

Building the API request URL

Once you’ve discovered a Freebox on the local network you can access the API at the following URL:

http://[freebox_ip]:[freebox_port]/[api_base_url]/v[major_api_version]/[api_url]

Example:

http://mafreebox.freebox.fr/api/v3/login/

API conventions

Most API uses the REST architecture, pay attention to the http methods used for each request.

The API response is always a JSON object using utf8 encoding.

APIResponse
success boolean Read-only

indicates if the request was successful

result object Read-only

the result of the request.

(It may be omitted if the request does not expect any result)

error_code string Read-only

In case of request error, this error_code provides information about the error.

The possible error_code values are documented for each API.

msg string Read-only

In cas of error, provides a French error message relative to the error

Successful response example

{
   success: true,
   result: {
      logged_in: false,
      challenge: "WpsbHdkBpRpHLMGQHZ1ri1uUqa4ce6Dw"
   }
}

Error response example

{
   msg: "Requête invalide",
   success: false,
   error_code: "invalid_request"
}

The HTTP response code can also be used to error reason, for instance if you attempt to access to an API with invalid credential you will get a 403 error, or if you attempt to call an API with an invalid path you will get a 404 error.

Authentication

Unless otherwise stated API access must be authenticated using the procedure described in the following document