Data Types

FormDataUpload

Upload multiple files with a single HTTP request, using multipart form data:

POST /v2/accounts/{accountId}/uploads/form_data
cURL
1curl "https://api.upload.io/v2/accounts/{accountId}/uploads/form_data" \
2 -H "Authorization: Bearer YOUR_API_KEY" \
3 -F file=@image.jpg # File must exist locally. Always include the '@'.
Response (200)
1{
2 "errors": [
3 {
4 "error": {
5 "code": "error_code",
6 "message": "Error message."
7 },
8 "formDataFieldName": "file"
9 }
10 ],
11 "files": [
12 {
13 "accountId": "YOUR_ACCOUNT_ID",
14 "filePath": "/uploads/file.txt",
15 "fileUrl": "https://upcdn.io/A623uY2/raw/uploads/file.txt",
16 "formDataFieldName": "file"
17 }
18 ]
19}

Request Body

Multipart form data containing the files to upload.

Each multipart form data part must include:

  • The file's contents.
  • The file's MIME type.
  • The file's name (optional).

Response Body

URL Parameters

accountId

Your account ID.

This is visible on the settings page:

https://upload.io/dashboard/settings

Example: A623uY2

Type: String

Length: 7

In: Path

Required: Yes

fileName

The file name to upload the file with.

Must not contain /.

Supports path variables.

Conditional: only allowed if filePath is not set.

Example: ?fileName=image.jpg

Type: String

Min Length: 0

Max Length: 512

In: Querystring

Required: No

fileNameFallback

The file name to use if fileName is already taken.

Must not contain /.

Supports path variables.

Conditional: only allowed if fileName is set.

Example: ?fileNameFallback=image.jpg

Type: String

Min Length: 0

Max Length: 512

In: Querystring

Required: No

fileNameVariablesEnabled

If true then path variables like {UTC_DATE} in the fileName will be replaced. You can escape { characters with a \.

If false then path variables like {UTC_DATE} in the fileName will be taken literally.

Default: true

Type: Boolean

In: Querystring

Required: No

filePath

The path to upload the file to (including the file's name).

Must begin with / and should end with the file's name.

Does not support path variables.

Conditional: only include if both fileName and folderPath are not set.

Example: ?filePath=/uploads/image.jpg

Type: String

Min Length: 0

Max Length: 512

In: Querystring

Required: No

folderPath

The path to upload the file to (excluding the file's name).

Must begin with / but should not end with /.

Supports path variables.

Conditional: only allowed if filePath is not set.

Example: ?folderPath=/uploads

Type: String

Min Length: 0

Max Length: 512

In: Querystring

Required: No

folderPathVariablesEnabled

If true then path variables like {UTC_DATE} in the folderPath will be replaced. You can escape { characters with a \.

If false then path variables like {UTC_DATE} in the folderPath will be taken literally.

Default: true

Type: Boolean

In: Querystring

Required: No

tag

The tags you specify here determine which rules will be executed for the upload.

You create rules in the Upload Dashboard, and choose which tags trigger each rule.

Rules include: max file size checks, traffic limit checks, rate limit checks, etc.

This parameter can be set multiple times.

Example: ?tag=example_tag&tag=example_tag

Type: String

In: Querystring

Required: No

Request Headers

Authorization

Add one of these Authorization header values to your request:

Option 1: prefix "Bearer " to your API key. The result is your Authorization header value.

Option 2: use HTTP basic authorization, specifying apikey as your username, and your API key as your password.

Type: String

In: Header

Required: Yes

Content-Type

This endpoints requires a multipart form data body.

Type: String

Value: "multipart/form-data"

In: Header

Required: Yes

X-Upload-Metadata

Arbitrary JSON to store against the file as metadata.

You can retrieve this later via a GetFileDetails request.

Header value must be a complex JSON object, and not wrapped in quotes, e.g. { "hello": "world" }

Type: FileMetadata

In: Header

Required: No

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: