Table Of Contents

Previous topic

VPN Client [UNSTABLE]

Next topic

Parental Control

Storage API [UNSTABLE]

This API allows you to manage the Freebox internal disk and disks connected to the Freebox

This API is unstable, it can be modified without notice in next releases.

Storage API Errors

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

error_code Description
not_found No disk/partition with this id
invalid_disk No such disk
is_a_partition This is not a disk but a partition
is_internal This action is not permitted on internal disk
op_not_supported Operation not supported
op_failed Operation failed
disk_busy Disk is busy

Disk Partition object

Operation progress has the following attributes:

OperationProgress
done_steps int Read-only

number of steps done

max_steps int Read-only

total number of steps

percent int Read-only

current step progress

Disk partitions have the following attributes:

DiskPartition
id int Read-only

unique partition id

disk_id int Read-only

related disk id

state enum
state Description
error Partition has error
checking Partition check in progress
formatting Partition format in progress
mounting Partition mount in progress
maintenance Partition is in maintenance mode
mounted Partition is ready
umounting Partition umount in progress
umounted Partition is umounted
ejecting Partition ejection in progress
fstype enum Read-only
fstype  
empty  
unknown  
xfs  
ext4  
vfat  
ntf  
hf  
hfsplus  
swap  
exfat  
label string

partition name

path string Read-only

partition mount point (encoded in base64 as explained in fs API)

total_bytes int Read-only

partition size (in bytes)

used_bytes int Read-only

partition used space (in bytes)

free_bytes int Read-only

partition free space (in bytes)

fsck_result enum Read-only

fsck result

state Description
no_run_yet Partition has not been checked yet
running Check is in progress
fs_clean File system is ok
fs_corrected File system was corrected
fs_needs_correction File system need correction
failed File system has unrecoverable error
operation_pct OperationProgress Read-only

partition operation progress

Storage Disk object

Storage disks have the following attributes:

StorageDisk
id int Read-only

the disk id

type enum Read-only
type Description
internal Freebox internal disk
usb usb disk
sata sata disk
state enum
state Description
error Disk has error
disabled Disk is disabled
enabled Disk is enabled
formatting Disk is formatting
connector int Read-only

Disk physical connector id

total_bytes int Read-only

Disk size (in bytes)

table_type int Read-only
table_type  
msdos  
gpt  
superfloppy  
empty  
model string Read-only

Disk model

serial string Read-only

Disk serial number

firmware string Read-only

Disk firmware version

temp int Read-only

Disk temperature (when supported) in °C

operation_pct OperationProgress Read-only

partition operation progress

partitions[] array of DiskPartition Read-only

list of disk partitions

idle bool Read-only

is disk idle (when available)

idle_duration int Read-only

disk idle duration (in seconds) (when available)

spinning bool Read-only

is disk spinning (when available)

active_duration int Read-only

disk activity duration (in seconds) (when available)

time_before_spindown int Read-only

seconds left before disk spin down (in seconds) (when available)

Storage Disk API

Get the list of disks

GET /api/v3/storage/disk/

Returns the collection of all StorageDisk

Example request:

GET /api/v3/storage/disk/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": [
        {
            "idle_duration": 368,
            "spinning": true,
            "table_type": "msdos",
            "firmware": "PB2ICC0E",
            "type": "internal",
            "idle": true,
            "connector": 0,
            "id": 1,
            "state": "enabled",
            "time_before_spindown": 232,
            "total_bytes": 250059350016,
            "model": "Hitachi HCC545025B9A300",
            "active_duration": 0,
            "temp": 51,
            "serial": "GSCH35VC",
            "partitions": [
                {
                    "fstype": "ext4",
                    "total_bytes": 245091500032,
                    "label": "Disque dur",
                    "id": 3,
                    "fsck_result": "no_run_yet",
                    "state": "mounted",
                    "disk_id": 1,
                    "free_bytes": 68120969216,
                    "used_bytes": 164520534016,
                    "path": "L0Rpc3F1ZSBkdXI="
                }
            ]
        },
        {
            "type": "usb",
            "total_bytes": 125435904,
            "connector": 1,
            "id": 1001,
            "active_duration": 0,
            "partitions": [
                {
                    "fstype": "ext4",
                    "total_bytes": 121418752,
                    "label": "Disque 1",
                    "id": 1002,
                    "fsck_result": "no_run_yet",
                    "state": "mounted",
                    "disk_id": 1001,
                    "free_bytes": 108904448,
                    "used_bytes": 6245376,
                    "path": "L0Rpc3F1ZSAx"
                }
            ],
            "idle_duration": 0,
            "state": "enabled",
            "idle": false,
            "spinning": false,
            "model": "",
            "table_type": "gpt",
            "temp": 0,
            "serial": "",
            "firmware": ""
        }
    ]
}

Get a given disk info

GET /api/v3/storage/disk/{id}

Returns the StorageDisk with the given id

Example request:

GET /api/v3/storage/disk/1 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "idle_duration": 464,
        "spinning": true,
        "table_type": "msdos",
        "firmware": "PB2ICC0E",
        "type": "internal",
        "idle": true,
        "connector": 0,
        "id": 1,
        "state": "enabled",
        "time_before_spindown": 136,
        "total_bytes": 250059350016,
        "model": "Hitachi HCC545025B9A300",
        "active_duration": 0,
        "temp": 51,
        "serial": "GSCH35VC",
        "partitions": [
            {
                "fstype": "ext4",
                "total_bytes": 245091500032,
                "label": "Disque dur",
                "id": 3,
                "fsck_result": "no_run_yet",
                "state": "mounted",
                "disk_id": 1,
                "free_bytes": 68120969216,
                "used_bytes": 164520534016,
                "path": "L0Rpc3F1ZSBkdXI="
            }
        ]
    }
}

Update a disk state

PUT /api/v3/storage/disk/{id}

Enable/Disable a disk

Example request:

PUT /api/v3/storage/disk/1 HTTP/1.1
Host: mafreebox.freebox.fr
{
   "state": "disabled"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "type": "usb",
        "total_bytes": 125435904,
        "connector": 1,
        "id": 1001,
        "active_duration": 0,
        "partitions": [
            {
                "fstype": "ext4",
                "total_bytes": 121418752,
                "label": "Disque 1",
                "id": 1002,
                "fsck_result": "no_run_yet",
                "state": "umounted",
                "disk_id": 1001,
                "free_bytes": 108904448,
                "used_bytes": 6245376,
                "path": "L0Rpc3F1ZSAx"
            }
        ],
        "idle_duration": 0,
        "state": "disabled",
        "idle": false,
        "spinning": false,
        "model": "",
        "table_type": "gpt",
        "temp": 0,
        "serial": "",
        "firmware": ""
    }
}

Format a disk

PUT /api/v3/storage/disk/{id}/format/

Format the disk with the given id

To be able to format a disk you need to provide the following parameters (JSON encoded). There will be one partition using all the available space on disk. All previous data will be lost.

This parameters will be ignored if you format the Freebox internal disk

Parameters:
  • table_type (string) – The partition table format
  • fs_type (string) – The partition type
  • label (string) – The partition label

NOTE: once started you can monitor the format process getting the disk information (see StorageDisk operation_pct field)

Example request:

PUT /api/v3/fs/storage/disk/1001/format HTTP/1.1
Host: mafreebox.freebox.fr
{
   "label": "freebox",
   "fs_type": "vfat",
   "table_type": "msdos"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}

Storage Partition API

Get the list of partitions

GET /api/v3/storage/partition/

Returns the collection of all DiskPartition

Example request:

GET /api/v3/storage/partition/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": [
        {
            "fstype": "ext4",
            "total_bytes": 245091500032,
            "label": "Disque dur",
            "id": 3,
            "fsck_result": "no_run_yet",
            "state": "umounted",
            "disk_id": 1,
            "free_bytes": 68120969216,
            "used_bytes": 164520534016,
            "path": "L0Rpc3F1ZSBkdXI="
        },
        {
            "fstype": "vfat",
            "total_bytes": 123485184,
            "label": "freebox",
            "id": 1002,
            "fsck_result": "no_run_yet",
            "state": "mounted",
            "disk_id": 1001,
            "free_bytes": 123484672,
            "used_bytes": 512,
            "path": "L2ZyZWVib3g="
        }
    ]
}

Get a given partition info

GET /api/v3/storage/partition/{id}

Returns the DiskPartition with the given id

Example request:

GET /api/v3/storage/partition/1002 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "fstype": "vfat",
        "total_bytes": 123485184,
        "label": "freebox",
        "id": 1002,
        "fsck_result": "no_run_yet",
        "state": "mounted",
        "disk_id": 1001,
        "free_bytes": 123484672,
        "used_bytes": 512,
        "path": "L2ZyZWVib3g="
    }
}

Update a partition state

PUT /api/v3/storage/partition/{id}

Enable/Disable a partition

Example request:

PUT /api/v3/storage/partition/1 HTTP/1.1
Host: mafreebox.freebox.fr
{
   "state" : "umounted"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "fstype": "vfat",
        "total_bytes": 123485184,
        "label": "freebox",
        "id": 1002,
        "fsck_result": "no_run_yet",
        "state": "umounted",
        "disk_id": 1001,
        "free_bytes": 123484672,
        "used_bytes": 512,
        "path": "L2ZyZWVib3g="
    }
}

Check a partition

PUT /api/v3/storage/partition/{id}/check/

Checks the partition with the given id

To be able to check a partition you need to provide the following parameters (JSON encoded):

Parameters:
  • checkmode (enum) – ‘ro’ for read only check, ‘rw’ to attempt to repair errors

NOTE: once started you can monitor the fsck process getting the partition information (see DiskPartition operation_pct field)

Example request:

PUT /api/v3/fs/storage/partition/1002/check HTTP/1.1
Host: mafreebox.freebox.fr
{
   "checkmode": "ro"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}