Upload Files

Uploads one or more files to ftpGrid storage using multipart/form-data.

The endpoint supports:

• Single-file uploads
• Multi-file uploads
• Recursive directory creation
• Destination path mapping
• Automatic overwrite handling

Uploaded files overwrite existing files with the same path and filename.

When overwriting an existing file, the metadata updated_at timestamp is updated automatically.

Required Scope

file.create

Endpoint

POST /api/upload

Example Request (HTTPie)

http --form POST https://webN.ftpgrid.com/api/upload \
    Authorization:"Bearer YOUR_TOKEN" \
    f1@"./testupload1.txt" \
    f2@"./testhtml.html" \
    meta='{
        "files":[
            {
                "field":"f1",
                "path":"/"
            },
            {
                "field":"f2",
                "path":"a/recursive/path/"
            }
        ]
    }'

Multipart Structure

Field	Type	Description
f1	binary file	Uploaded file
f2	binary file	Uploaded file
meta	JSON string	Upload metadata configuration

Metadata JSON

{
    "files": [
        {
            "field": "f1",
            "path": "/"
        },
        {
            "field": "f2",
            "path": "a/recursive/path/"
        }
    ]
}

Metadata Fields

Field	Type	Description
field	string	Multipart field name
path	string	Destination directory path

Example Response

{
    "rslt": "OK"
}

Metadata Behavior

• Metadata is optional
• If metadata is omitted, all files are uploaded to /
• Metadata mappings must be complete
• Partial metadata definitions are not supported
• Every uploaded file must have a matching metadata entry when metadata is used

Directory Creation

Destination directories are automatically created if they do not exist.

Recursive directory creation is supported.

Example:

a/recursive/path/

automatically creates:

/a
/a/recursive
/a/recursive/path

Notes

• Existing files are overwritten automatically
• Overwriting a file updates the updated_at metadata timestamp
• Multiple files may be uploaded in a single request
• Uploads use multipart/form-data
• Paths are UNIX-style paths
• Paths may contain spaces and UTF-8 characters
• Paths are automatically sanitized and normalized
• Invalid or unsafe paths are rejected
• Uploads are streamed directly to storage
• Metadata propagation may be eventually consistent immediately after upload
• Very large uploads may be subject to account quotas and upload limits