Table Of Contents

Previous topic

File Sharing Link

Next topic

AirMedia API

File Upload

This API allows you to upload files to the Freebox Server.

NOTE: for large transfer files, you should prefer FTP over HTTP transfer

Overall process

To be able to upload a file to the Freebox Server you will need an upload authorization id. This upload id will then allow you to send a file to the Freebox, and track the upload progress.

File Upload Errors

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

error_code Description
invalid_request Invalid request
path_not_found File or folder not found
access_denied Write permission denied in the destination folder
conflict A file with same name already exists
invalid_id Invalid file upload id

File Upload object

File uploads have the following attributes:

FileUpload
id string Read-only

upload id

size int Read-only

Upload file size in bytes

uploaded int Read-only

Uploaded bytes

status enum Read-only

upload status can have the following values

status Description
authorized Upload authorization is valid, upload has not started yet
in_progress Upload in progress
done Upload done
failed Upload failed
conflict Destination file conflict
timeout Upload authorization is no longer valid
cancelled Upload cancelled by user
start_date timestamp Read-only

upload start date

last_update timestamp Read-only

last update of file upload object

upload_name string Read-only

name of the file uploaded

dirname string Read-only

upload destination directory

File Upload API

Create a file upload authorization

POST /api/v3/upload/

Create a new upload authorization id

Example request:

POST /api/v3/upload/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "dirname": "L0Rpc3F1ZSAx", /* /Disque 1 */
   "upload_name": "test.txt"
}

Example response:

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

Uploading the file

POST /api/v3/upload/{id}/send

Send the content of the FileUpload task

NOTE: the content should be sent using multipart/form-data encoding

Example request:

POST /api/v3/upload/1219331316/send HTTP/1.1
Host: mafreebox.freebox.fr
Content-Length: 655
Content-Type: multipart/form-data; boundary=---------------------------5378523251169820641184848723

-----------------------------5378523251169820641184848723\r\n
Content-Disposition: form-data; name="reboot.png"; filename="reboot.png"\r\n
Content-Type: image/png\r\n
\r\n
\x89PNG\r\n
\x1a\n

[ ... ]

Example response:

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

Get the list of uploads

GET /api/v3/upload/

Example request:

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

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": [
        {
            "id": 1678139709,
            "size": 54960,
            "uploaded": 54960,
            "status": "done",
            "last_update": 1361465608,
            "start_date": 1361465608,
            "upload_name": "playlist.m3u",
            "dirname": "/Disque 1"
        }
    ]
}

Track an upload status

GET /api/v3/upload/{id}

With this API you can track the progress of your FileUpload task

Example request:

GET /api/v3/upload/1678139709 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "id": 1678139709,
        "size": 54960,
        "uploaded": 54960,
        "status": "done",
        "last_update": 1361465608,
        "start_date": 1361465608,
        "upload_name": "playlist.m3u",
        "dirname": "/Disque 1"
    }
}

Cancel an upload

DELETE /api/v3/upload/{id}/cancel

Cancel the given FileUpload closing the connection The upload status must be in_progress

Example request:

DELETE /api/v3/upload/136419941/cancel HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

Delete an upload

DELETE /api/v3/upload/{id}

Delete the given FileUpload closing the connection if needed

Example request:

DELETE /api/v3/upload/136419941 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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

Cleanup all terminated uploads

DELETE /api/v3/upload/clean

Deletes all the FileUpload not in_progress

Example request:

DELETE /api/v3/upload/clean HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

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