---
title: "Upload files"
method: POST
path: "/Fileman/upload_files"
tags: ["Fileman", "Manage Files"]
---

# Upload files

`POST /Fileman/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](https://go.cpanel.net/serverroles)
  role, the system **disables** this function.
* You cannot call this function through WHM API 1's
  [uapi_cpanel](https://go.cpanel.net/UseWHMAPItoCallcPanelAPIandUAPI)
  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).

## Query parameters

- `dir` string, path
- `get_disk_info` 0 | 1
- `overwrite` 0 | 1
- `permissions` string, unix-file-permission

## Response `200`

HTTP Request was successful.

- object
  - `apiversion` integer — The version of the API.
  - `func` string — The name of the method called.
  - `module` string — The name of the module called.
  - `result` object
    - `data` object
      - `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 (∞).
        - `file_upload_max_bytes` string — The largest size, in bytes, that a single uploaded file may reach.
        - `file_upload_must_leave_bytes` string — The amount of free space, in bytes, that must remain after an upload.
        - `file_upload_remain` string — The total size, in bytes, that the account may upload now.
        - `fileslimit` union — The number of inodes that the account may use.
          - integer
          - string
        - `filesremain` union — The number of inodes that the account may still use.
          - integer
          - string
        - `filesused` union — The number of inodes that the account uses.
          - integer
          - string
        - `spacelimit` string — The disk space, in bytes, that the account may use.
        - `spaceremain` string — The disk space, in bytes, that the account may still use.
        - `spaceused` string — The disk space, in bytes, that the account uses.
      - `failed` integer — The number of files that the system did not store.
      - `succeeded` integer — The number of files that the system stored.
      - `uploads` object[] — One entry for each file in the request.
        - `file` string — The file's name.
        - `reason` string — A description of the outcome for this file.
        - `size` integer, nullable — The stored file's size, in bytes. The system returns `null` when the upload failed.
        - `status` 0 | 1 — * `1` - The system stored the file. * `0` - The upload failed. Check the `reason` value.
        - `warnings` string[] — Non-critical problems, such as a failure to apply the file's ownership or permissions.
      - `warned` integer — The number of files that produced warnings.
    - `errors` string[], nullable — 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.
    - `messages` string[], nullable — List of messages generated by the API.
    - `metadata` object
    - `status` 0 | 1 — - 1 - Success - 0 - Failed: Check the errors field for more details.
    - `warnings` string[], nullable — List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.

---

[API](https://skmtc.net/cpanel/apis/cpanel-uapi.md) · [All operations](https://skmtc.net/cpanel/apis/cpanel-uapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cpanel/cpanel-uapi/versions/632e2f8e6d04/schema)