Skip to content
Nhost Documentation
Support Dashboard

Upload files

POST
/files

Upload one or more files to a specified bucket. Supports batch uploading with optional custom metadata for each file. If uploading multiple files, either provide metadata for all files or none.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

File upload data including files and optional metadata

object
bucket-id

Target bucket identifier where files will be stored.

string
Example
user-uploads
metadata[]

Optional custom metadata for each uploaded file. Must match the order of the file[] array.

Array<object>

Metadata provided when uploading a new file.

object
id

Optional custom ID for the file. If not provided, a UUID will be generated.

string
Example
custom-id-123
name

Name to assign to the file. If not provided, the original filename will be used.

string
Example
custom-filename.png
metadata

Custom metadata to associate with the file.

object
key
additional properties
any
Example
{
  "alt": "Custom image",
  "category": "document"
}
file[]
required

Array of files to upload.

Array<string>

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Files successfully uploaded

object
processedFiles
required

List of successfully processed files with their metadata.

Array<object>

Comprehensive metadata information about a file in storage.

object
id
required

Unique identifier for the file.

string
Example
d5e76ceb-77a2-4153-b7da-1f7c115b2ff2
name
required

Name of the file including extension.

string
Example
profile-picture.jpg
size
required

Size of the file in bytes.

integer format: int64
Example
245678
bucketId
required

ID of the bucket containing the file.

string
Example
users-bucket
etag
required

Entity tag for cache validation.

string
Example
"a1b2c3d4e5f6"
createdAt
required

Timestamp when the file was created.

string format: date-time
Example
2023-01-15T12:34:56Z
updatedAt
required

Timestamp when the file was last updated.

string format: date-time
Example
2023-01-16T09:45:32Z
isUploaded
required

Whether the file has been successfully uploaded.

boolean
Example
true
mimeType
required

MIME type of the file.

string
Example
image/jpeg
uploadedByUserId

ID of the user who uploaded the file.

string
Example
abc123def456
metadata

Custom metadata associated with the file.

object
key
additional properties
any
Example
{
  "alt": "Profile picture",
  "category": "avatar"
}

default

Section titled “default ”

Error occurred during upload

Error information returned by the API.

object
processedFiles

List of files that were successfully processed before the error occurred.

Array<object>

Comprehensive metadata information about a file in storage.

object
id
required

Unique identifier for the file.

string
Example
d5e76ceb-77a2-4153-b7da-1f7c115b2ff2
name
required

Name of the file including extension.

string
Example
profile-picture.jpg
size
required

Size of the file in bytes.

integer format: int64
Example
245678
bucketId
required

ID of the bucket containing the file.

string
Example
users-bucket
etag
required

Entity tag for cache validation.

string
Example
"a1b2c3d4e5f6"
createdAt
required

Timestamp when the file was created.

string format: date-time
Example
2023-01-15T12:34:56Z
updatedAt
required

Timestamp when the file was last updated.

string format: date-time
Example
2023-01-16T09:45:32Z
isUploaded
required

Whether the file has been successfully uploaded.

boolean
Example
true
mimeType
required

MIME type of the file.

string
Example
image/jpeg
uploadedByUserId

ID of the user who uploaded the file.

string
Example
abc123def456
metadata

Custom metadata associated with the file.

object
key
additional properties
any
Example
{
  "alt": "Profile picture",
  "category": "avatar"
}
error

Error details.

object
message
required

Human-readable error message.

string
Example
File not found
data

Additional data related to the error, if any.

object
key
additional properties
any