# Upload files

This function uploads one or more files to a directory.

Important:

* You must send the files as parts of a multipart/form-data request
  body. Query parameters cannot carry a file. For security reasons, the
  system discards any query parameter whose name begins with file-.
* You can't pass the file parts on the command line, and LiveAPI can't
  call this function at all, because neither can send a
  multipart/form-data body.
* When you disable the File Storage
  role, the system disables this function.
* You cannot call this function through WHM API 1's
  uapi_cpanel
  function.

Note:

* The system names each stored file after that part's filename
  attribute, not after the form field's name. By convention, name the
  fields file-0, file-1, and so on, as the cPanel interface does.
* The system scans every uploaded file for viruses and rejects an
  infected file.
* The system rejects a filename of . or .., or a filename that
  contains control characters or any of the `, ;, and /
  characters.
* If one request contains two files with the same name, the system
  renames the second file. For example, example-2.png.
* For more information about how to use this function in your custom
  code, read our [Use UAPI's Fileman::upload_files` Function in Custom
  Code tutorial](https://go.cpanel.net/tutorial-use-uapis-fileman-upload-files-function-in-custom-code).

Endpoint: POST /Fileman/upload_files
Version: 11.138.0.10
Security: BasicAuth

## Query parameters:

  - `dir` (string)
    The directory in which to store the uploaded files.

Note:

* A relative path resolves against the account's home directory.
* This parameter defaults to the account's home directory.
* The system creates the directory if it does not exist.
    Example: "/home/username/public_html"

  - `get_disk_info` (integer)
    Whether to include the account's disk usage in the response.

* 1 - Return the diskinfo object.
* 0 - Do not return the diskinfo object.
    Enum: 0, 1

  - `overwrite` (integer)
    Whether to replace a file that already exists in the target directory.

* 1 - Overwrite the existing file.
* 0 - Fail that file with an "already exists" reason.
    Enum: 0, 1

  - `permissions` (string)
    The permissions to apply to every file in the request, in octal
notation.

Note:

* The system reads both 0644 and 644 as octal.
* This parameter defaults to 0644.
* If the system cannot apply the permissions, the upload still succeeds
  and the function returns a warning for that file.
    Example: "0600"

## Request fields (multipart/form-data):

  - `file-0` (string, required)
    A file to upload.

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "upload_files"

  - `module` (string)
    The name of the module called.
    Example: "Fileman"

  - `result` (object)

  - `result.data` (object)

  - `result.data.diskinfo` (object)
    The account's disk usage and upload limits. The
system only returns this object when you pass
the get_disk_info parameter.

Note:

* The object also contains a _humansize variant
  of every value below, formatted for display. For
  example, spaceused_humansize.
* The system returns each byte count as a decimal
  string with two decimal places, and each inode
  count as a number.
* A value that the account's quota does not limit
  appears as an infinity symbol (∞).

  - `result.data.diskinfo.file_upload_max_bytes` (string)
    The largest size, in bytes, that a single uploaded file may reach.
    Example: "104857600.00"

  - `result.data.diskinfo.file_upload_must_leave_bytes` (string)
    The amount of free space, in bytes, that must remain after an upload.
    Example: "5242880.00"

  - `result.data.diskinfo.file_upload_remain` (string)
    The total size, in bytes, that the account may upload now.
    Example: "4718592.00"

  - `result.data.diskinfo.fileslimit` (any)
    The number of inodes that the account may use.
    Example: 16896

  - `result.data.diskinfo.filesremain` (any)
    The number of inodes that the account may still use.
    Example: 15872

  - `result.data.diskinfo.filesused` (any)
    The number of inodes that the account uses.
    Example: 1024

  - `result.data.diskinfo.spacelimit` (string)
    The disk space, in bytes, that the account may use.
    Example: "4718592.00"

  - `result.data.diskinfo.spaceremain` (string)
    The disk space, in bytes, that the account may still use.
    Example: "2359296.00"

  - `result.data.diskinfo.spaceused` (string)
    The disk space, in bytes, that the account uses.
    Example: "2359296.00"

  - `result.data.failed` (integer)
    The number of files that the system did not store.

  - `result.data.succeeded` (integer)
    The number of files that the system stored.
    Example: 1

  - `result.data.uploads` (array)
    One entry for each file in the request.

  - `result.data.uploads.file` (string)
    The file's name.
    Example: "example.png"

  - `result.data.uploads.reason` (string)
    A description of the outcome for this file.
    Example: "Upload of “example.png” succeeded."

  - `result.data.uploads.size` (integer,null)
    The stored file's size, in bytes. The system returns null when the upload failed.
    Example: 268

  - `result.data.uploads.status` (integer)
    * 1 - The system stored the file.
* 0 - The upload failed. Check the reason value.
    Enum: 0, 1

  - `result.data.uploads.warnings` (array)
    Non-critical problems, such as a failure to apply the file's ownership or permissions.

  - `result.data.warned` (integer)
    The number of files that produced warnings.

  - `result.errors` (array,null)
    List of errors if the API failed. This function returns
one of the following errors:

* You must specify at least one file to upload. - The
  request contained no file. The system also returns
  this error when it discarded the request's only file
  for exceeding the file_upload_max_bytes limit or for
  leaving less than file_upload_must_leave_bytes of
  free space.
* Failed to upload any of the requested files with
  various failures. - Every file failed. Check each
  entry's reason value in the uploads array.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.status` (integer)
    - 1 - Success
- 0 - Failed: Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.