File System¶

With the file system API you can access files on Freebox internal disk and disks connected to the Freebox.

Path encoding¶

NOTE:

For maximum compatibility issues path are encoded in base64, you should use the path as it is returned by the ls API call.

For instance this will solve problems with unicode equivalence .

Although “Spécial” (0x53 0x70 0xc3 0xa9 0x63 0x69 0x61 0x6c) and “Spécial” (0x53 0x70 0x65 0xcc 0x81 0x63 0x69 0x61 0x6c) are utf8 equivalent, it is represents two different path.

Some software/libraries will replace the original string with its normalized form, causing issues. The use of base64 encoded path will ensure the original path will be preserved.

File System Errors¶

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

error_code	Description
invalid_id	Invalid object id
path_not_found	File or folder not found
internal_error	Internal error
disk_unavailable	The disk is not mounted
invalid_request	Invalid request
invalid_conflict_mode	The conflict mode specified is invalid (see below)
exec_failed	Internal error
out_of_memory	Out of memory
task_not_found	Invalid task id
invalid_state	You tried to set an invalid state
invalid_task_type	This operation cannot be performed on this task
destination_conflict	The destination file/folder already exists
access_denied	Access to this file is denied
disk_full	The destination disk is full

Task¶

File system tasks have the following attributes:

FsTask¶

id int Read-only¶: id

type enum Read-only¶

The valid task types are:

Type	Description
cat	Concatenate multiple files
cp	Copy files
mv	Move files
rm	Remove files
archive	Creates an archive
extract	Extract an archive
repair	Check and repair files

state enum¶

State	Description
queued	Queued (only one task is active at a given time)
running	Running
paused	Paused (user suspended)
done	Done
failed	Failed (see error)

error enum Read-only¶

Error	Description
none	No error
archive_read_failed	Error reading archive
archive_open_failed	Error opening archive
archive_write_failed	Error writing archive
chdir_failed	Error changing directory
dest_is_not_dir	The destination is not a directory
file_exists	File already exists
file_not_found	File not found
mkdir_failed	Unable to create directory
open_input_failed	Error opening input file
open_output_failed	Error opening output file
opendir_failed	Error opening directory
overwrite_failed	Error overwriting file
path_too_big	Path is too long
repair_failed	Failed to repair corrupted files
rmdir_failed	Error removing directory
same_file	Source and Destination are the same file
unlink_failed	Error removing file
unsupported_file_type	This file type is not supported
write_failed	Error writing file
disk_full	Disk is full
internal	Internal error
invalid_format	Invalid file format (corrupted ?)
incorrect_password	Invalid or missing password for extraction
permission_denied	Permission denied
readlink_failed	Failed to read the target of a symbolic link
symlink_failed	Failed to create a symbolic link

created_ts timestamp Read-only¶: task creation timestamp

started_ts timestamp Read-only¶: task start timestamp

done_ts timestamp Read-only¶: task end timestamp

duration int Read-only¶: task duration in seconds

progress int Read-only¶: task progress in percent (scaled by 100)

eta int Read-only¶: estimated time remaining before the task completion (in seconds)

from string Read-only¶: current source file (if available)

to string Read-only¶: current destination file (if available)

nfiles int Read-only¶: number of files to process

nfiles_done int Read-only¶: number of files processed

total_bytes int Read-only¶: total bytes to process

total_bytes_done int Read-only¶: number of bytes processed

curr_bytes int Read-only¶: size of the file currently processed

curr_bytes_done int Read-only¶: number of bytes processed for the current file

rate int Read-only¶: processing rate in byte/s

List every tasks¶

GET /api/v4/fs/tasks/¶

Returns the collection of all FsTask tasks

Example request:

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

Example response:

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

{
   success: true,
   result: [
      {
         curr_bytes_done: 0,
         total_bytes: 0,
         nfiles_done: 0,
         started_ts: 1355834253,
         duration: 3,
         done_ts: 0,
         curr_bytes: 0,
         type: "extract",
         to: "oxygennosvg/128x128/mimetypes/application_x_nzb.png",
         id: 12,
         nfiles: 0,
         created_ts: 1355834253,
         state: "paused",
         total_bytes_done: 0,
         from: "/Disque dur/tests/oxygennosvg.tar.gz",
         rate: 0,
         eta: 0,
         error: "none",
         progress: 0
      },
      {
         id: 11,
         curr_bytes_done: 0,
         total_bytes: 0,
         nfiles_done: 0,
         started_ts: 1355834187,
         duration: 0,
         done_ts: 1355834187,
         curr_bytes: 0,
         type: "rm",
         to: "",
         nfiles: 0,
         created_ts: 1355834187,
         state: "done",
         total_bytes_done: 0,
         from: "/Disque dur/test/testiso.1.iso",
         rate: 0,
         eta: 0,
         error: "none",
         progress: 100
      }
   ]
}

List a task¶

GET /api/v4/fs/tasks/{id}¶

Returns the FsTask task with the given id

Example request:

GET /api/v4/fs/tasks/12 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
   success: true,
   result: {
      curr_bytes_done: 0,
      total_bytes: 0,
      nfiles_done: 0,
      started_ts: 1355834253,
      duration: 268,
      done_ts: 0,
      curr_bytes: 0,
      type: "extract",
      to: "oxygennosvg/16x16/actions/format_stroke_color.png",
      id: 12,
      nfiles: 0,
      created_ts: 1355834253,
      state: "running",
      total_bytes_done: 0,
      from: "/Disque dur/tests/oxygennosvg.tar.gz",
      rate: 0,
      eta: 0,
      error: "none",
      progress: 0
   }
}

Delete a task¶

DELETE /api/v4/fs/tasks/{id}¶

Deletes the FsTask task with the given id, if the task was running, stop it.

No rollback is done, if a file as already been processed it will be left as is.

Example request:

DELETE /api/v4/fs/tasks/12 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true
}

Update a task¶

PUT /api/v4/fs/tasks/{id}¶

Updates the FsTask task with the given id

Example request:

PUT /api/v4/fs/tasks/15 HTTP/1.1
Host: mafreebox.freebox.fr

{
   "state": "paused"
}

Example response:

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

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 2410125312,
        "nfiles_done": 0,
        "started_ts": 1355835094,
        "duration": 27,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "cp",
        "to": "/Disque dur/old_hdd/testiso.1.iso",
        "id": 15,
        "nfiles": 1,
        "created_ts": 1355835094,
        "state": "paused",
        "total_bytes_done": 595591168,
        "from": "/Disque dur/old_hdd/testiso.iso",
        "rate": 0,
        "eta": 85,
        "error": "none",
        "progress": 24
    }
}

Listing¶

File info¶

FileInfo¶

path string Read-only¶: file path (encoded in base64 as explained in Path Encoding)

name string Read-only¶: file name (in clear text)

mimetype string Read-only¶: file mimetype

type enum¶

Type	Description
dir	Directory
file	Regular file

size int Read-only¶: file size in bytes

modification int Read-only¶: file modification timestamp

index int Read-only¶: display order for natural sort

link boolean Read-only¶: is this file a link

target string Read-only¶: symlink target path (encoded in base64 as explained in Path Encoding) (only present when link is set to true)

hidden boolean Read-only¶: should the file be hidden to user

foldercount int Read-only¶

number of subfolders

only relevant for dir, only provided if “countSubFolder” parameter is set

filecount int Read-only¶

number of files inside directory

only relevant for dir, only provided if “countSubFolder” parameter is set

List files¶

GET /api/v4/fs/ls/{path}¶

Returns the list of FileInfos for the given path

Parameters:	onlyFolder (bool) – Only list folders countSubFolder (bool) – Return files and subfolder count for folders removeHidden (bool) – Don’t return hidden files in directory listing

Example request:

GET /api/v4/fs/ls/L0Rpc3F1ZSBkdXI= HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{

    "success": true,
    "result": [
        {
            "path": "L0Rpc3F1ZSBkdXIvRW5yZWdpc3RyZW1lbnRz",
            "filecount": 0,
            "link": false,
            "modification": 1362005535,
            "foldercount": 0,
            "name": "Enregistrements",
            "index": 1,
            "mimetype": "inode/directory",
            "hidden": false,
            "type": "dir",
            "size": 4096
        },

        /* Note: for the two following folders path are different, but name is utf8 equivalent */

        {
            "path": "L0Rpc3F1ZSBkdXIvTGUgU3DDqWNpYWwgMg==",
            "filecount": 0,
            "link": false,
            "modification": 1362492511,
            "foldercount": 0,
            "name": "Le Spécial 2",
            "index": 3,
            "mimetype": "inode/directory",
            "hidden": false,
            "type": "dir",
            "size": 4096
        },
        {
            "path": "L0Rpc3F1ZSBkdXIvTGUgU3BlzIFjaWFsIDI=",
            "filecount": 4,
            "link": false,
            "modification": 1361995307,
            "foldercount": 1,
            "name": "Le Spécial 2",
            "index": 4,
            "mimetype": "inode/directory",
            "hidden": false,
            "type": "dir",
            "size": 4096
        },

         [ ... ]

        {
            "path": "L0Rpc3F1ZSBkdXIvVmlkw6lvcw==",
            "filecount": 8,
            "link": false,
            "modification": 1361887598,
            "foldercount": 2,
            "name": "Vidéos",
            "index": 16,
            "mimetype": "inode/directory",
            "hidden": false,
            "type": "dir",
            "size": 4096
        }
    ]

}

Get file information¶

GET /api/v4/fs/info/{path}¶

Returns the FileInfos for the given path

Example request:

GET /api/v4/fs/info/L0Rpc3F1ZSBkdXIvdG90bw== 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": "dir",
        "link": true,
        "parent": "L0Rpc3F1ZSBkdXI=",
        "modification": 1370354349,
        "hidden": false,
        "mimetype": "inode/directory",
        "name": "toto",
        "target": "L0Rpc3F1ZSBkdXIvUGhvdG9z",
        "path": "L0Rpc3F1ZSBkdXIvdG90bw==",
        "size": 4096
    }
}

Operations¶

Each time you want to perform a modification on the file system you will have to create a new FsTask that you will be able to monitor.

NOTE: The requested operation may be en-queued to avoid performance drop because of excessive disk io

Conflict resolution¶

For certain file operations where a file name conflict can happen, you must specify a conflict resolution mode.

Valid resolution modes are:

Conflict mode	Description
overwrite	Overwrite the destination file
both	Keep both files (rename the file adding a suffix)
recent	Only overwrite if newer than destination file
skip	Keep the destination file

Move files¶

POST /api/v4/fs/mv/¶

Parameters:	files (string[]) – The list of files to move dst (string) – The destination mode (enum) – The conflict resolution mode

Example request for moving files:

POST /api/v4/fs/mv/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "files":
      [
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0RTQ18zNDkxLmpwZw==", /* /Disque dur/Photos/DSC_3491.jpg */
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0RTQ18zNTAwLmpwZw==" /* /Disque dur/Photos/DSC_3500.jpg */
      ],
    "dst": "L0Rpc3F1ZSBkdXIvUGhvdG9zL0xhdW5jaHBhZA==", /* /Disque dur/Photos/Launchpad */
    "mode": "overwrite"
}

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355840585,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "mv",
        "to": "",
        "id": 39,
        "nfiles": 0,
        "created_ts": 1355840585,
        "state": "running",
        "total_bytes_done": 0,
        "from": "",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Copy files¶

POST /api/v4/fs/cp/¶

Parameters:	files (string[]) – The list of files to copy dst (string) – The destination mode (enum) – The conflict resolution mode

Example request:

POST /api/v4/fs/cp/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "files":
      [
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0xhdW5jaHBhZC9EU0NfMzQ5MS5qcGcK", /* /Disque dur/Photos/Launchpad/DSC_3491.jpg */
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0xhdW5jaHBhZC9EU0NfMzUwMC5qcGcK", /* /Disque dur/Photos/Launchpad/DSC_3500.jpg */
      ],
    "dst": "L0Rpc3F1ZSBkdXIvUGhvdG9zL1JvY2tldHMK", /* /Disque dur/Photos/Rockets */
    "mode": "both"
 }

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355840943,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "cp",
        "to": "",
        "id": 43,
        "nfiles": 0,
        "created_ts": 1355840943,
        "state": "running",
        "total_bytes_done": 0,
        "from": "",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Remove files¶

POST /api/v4/fs/rm/¶

Parameters:	files (string[]) – The list of files to remove

Example request:

POST /api/v4/fs/rm/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "files":
      [
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL1JvY2tldHMvRFNDXzM0OTEuanBnCg==", /* /Disque dur/Photos/Rockets/DSC_3491.jpg */
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL1JvY2tldHMvRFNDXzM1MDAuanBnCg==" /* /Disque dur/Photos/Rockets/DSC_3500.jpg */
      ]
 }

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355841064,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "rm",
        "to": "",
        "id": 45,
        "nfiles": 0,
        "created_ts": 1355841064,
        "state": "running",
        "total_bytes_done": 0,
        "from": "/Disque dur/Photos/Rockets/DSC_3491.jpg",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Cat files¶

POST /api/v4/fs/cat/¶

Parameters:	files (string[]) – The list of files to concatenate dst (string) – The destination multi_volumes (bool) – Enable multi-volumes mode, it will start at XXX001 and concatenate XXX002, XXX003, ... delete_files (bool) – Deletes source files overwrite (bool) – Overwrites the destination append (bool) – Append to the destination

Example request:

POST /api/v4/fs/cat/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "files":
      [
         "L0Rpc3F1ZSBkdXIvZmlsZTE=", /* /Disque dur/file1 */
         "L0Rpc3F1ZSBkdXIvZmlsZTI="  /* /Disque dur/file2 */
      ],
    "dst": "L0Rpc3F1ZSBkdXIvZmlsZTEy", /* /Disque dur/file12 */
    "multi_volumes": false,
    "delete_files": false,
    "append": true,
    "overwrite": false
}

Or if you want to do a multi-volumes concatenation:

{
   "files":
      [
         // You don't need to specify file002, file003, ...
         // They'll be found by cat.
         "L0Rpc3F1ZSBkdXIvZmlsZTAwMQ==", /* /Disque dur/file001 */
      ],
    "dst": "L0Rpc3F1ZSBkdXIvZmlsZQ==", /* /Disque dur/file */
    "multi_volumes": true,
    "delete_files": true,
    "append": false,
    "overwrite": true
}

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355840943,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "cat",
        "to": "",
        "id": 43,
        "nfiles": 0,
        "created_ts": 1355840943,
        "state": "running",
        "total_bytes_done": 0,
        "from": "",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Create an archive¶

POST /api/v4/fs/archive/¶

Parameters:	files (string[]) – The list of files to archive dst (string) – The destination

Example request:

POST /api/v4/fs/archive/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "files":
      [
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0xhdW5jaHBhZC9EU0NfMzQ5MS5qcGc=", /* /Disque dur/Photos/Launchpad/DSC_3491.jpg */
         "L0Rpc3F1ZSBkdXIvUGhvdG9zL0xhdW5jaHBhZC9EU0NfMzUwMC5qcGc="  /* /Disque dur/Photos/Launchpad/DSC_3500.jpg */
      ],
    "dst": "L0Rpc3F1ZSBkdXIvUGhvdG9zL3JvY2tldHMuemlw" /* /Disque dur/Photos/rockets.zip */
 }

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355840943,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "archive",
        "to": "",
        "id": 42,
        "nfiles": 0,
        "created_ts": 1355840943,
        "state": "running",
        "total_bytes_done": 0,
        "from": "",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Extract a file¶

POST /api/v4/fs/extract/¶

Parameters:	src (string) – The archive file dst (string) – The destination folder password (string) – The archive password delete_archive (boolean) – Delete archive after extraction overwrite (boolean) – Overwrite files on conflict

Example request:

POST /api/v4/fs/extract/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "src": "L0Rpc3F1ZSBkdXIvb2xkX2hkZC90ZXN0aXNvLjEuaXNv", /* /Disque dur/old_hdd/testiso.1.iso */
   "dst": "L0Rpc3F1ZSBkdXIvb2xkX2hkZA==" /* /Disque dur/old_hdd */
   "password": "",
   "delete_archive": false,
   "overwrite": true
}

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355842252,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "extract",
        "to": "/Disque dur/old_hdd",
        "id": 48,
        "nfiles": 0,
        "created_ts": 1355842252,
        "state": "running",
        "total_bytes_done": 0,
        "from": "/Disque dur/old_hdd/testiso.1.iso",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Repair a file¶

POST /api/v4/fs/repair/¶

Parameters:	src (string) – The .par2 file delete_archive (boolean) – Delete par2 files after repair

Example request:

POST /api/v4/fs/repair/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "src": "L0Rpc3F1ZSBkdXIvdGVzdHMvcGFyMi9saWNlbnNlLnR4dC5wYXIy", /* /Disque dur/tests/par2/license.txt.par2 */
   "delete_archive": false
}

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 0,
        "nfiles_done": 0,
        "started_ts": 1355842559,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 0,
        "type": "repair",
        "to": "",
        "id": 50,
        "nfiles": 0,
        "created_ts": 1355842559,
        "state": "running",
        "total_bytes_done": 0,
        "from": "",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Hash a file¶

POST /api/v4/fs/hash/¶

Parameters:	src (string) – The file to hash hash_type (string) – The type of hash (md5, sha1, ...)

Example request:

POST /api/v4/fs/hash/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "src": "L0Rpc3F1ZSBkdXIvbXlfZmlsZQ==", /* /Disque dur/my_file */
   "hash_type": "md5"
}

Example response:

{
    "success": true,
    "result": {
        "curr_bytes_done": 0,
        "total_bytes": 4242,
        "nfiles_done": 0,
        "started_ts": 1355842559,
        "duration": 0,
        "done_ts": 0,
        "curr_bytes": 4242,
        "type": "hash",
        "to": "",
        "id": 50,
        "nfiles": 1,
        "created_ts": 1355842559,
        "state": "running",
        "total_bytes_done": 0,
        "from": "/Disque dur/my_file",
        "rate": 0,
        "eta": 0,
        "error": "none",
        "progress": 0
    }
}

Get the hash value¶

To get the hash, the task must have succeed and be in the state “done”.

GET /api/v4/fs/tasks/{id}/hash¶

Example request:

GET /api/v4/fs/tasks/50/hash HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

{
    "success": true,
    "result": {
        "hash": "94baaad4d1347ec6e15ae35c88ee8bc8"
    }
}

Create a directory¶

Contrary to other file system tasks, this operation is done synchronously.

Instead of a returning a FsTask a call to this API will only return success status

POST /api/v4/fs/mkdir/¶

Parameters:	parent (string) – The parent directory path (base64 encoded) dirname (string) – The name of the directory to create

Example request:

POST /api/v4/fs/mkdir/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "parent": "L0Rpc3F1ZSBkdXI=", /* /Disque dur */
   "dirname": "Test"
}

Example response:

{
    "success": true
}

Rename a file/folder¶

Contrary to other file system tasks, this operation is done synchronously.

Instead of a returning a FsTask a call to this API will only return success status and the new path as a result

POST /api/v4/fs/rename/¶

Parameters:	src (string) – The source file path (base64 encoded) dst (string) – The new name of the file (clear text, without path)

Example request:

POST /api/v4/fs/rename/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "src": "L0Rpc3F1ZSBkdXIvdGVzdC50eHQ=", /* /Disque dur/test.txt */
   "dst": "plop.txt"
}

Example response:

{
    "success": true,
    "result": "L0Rpc3F1ZSBkdXIvcGxvcC50eHQ=" /* /Disque dur/plop.txt */
}

Download a file¶

GET /api/v4/dl/{path}¶

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 600864
Content-Disposition: attachment; filename="Plans secrets.jpg"

[ ... ]