POST
/
files
Upload files
curl --request POST \
  --url https://{subdomain}.storage.{region}.nhost.run/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form bucket-id=user-uploads \
  --form 'metadata[]={
  "id": "custom-id-123",
  "name": "custom-filename.png",
  "metadata": {
    "alt": "Custom image",
    "category": "document"
  }
}'
{
  "processedFiles": [
    {
      "id": "d5e76ceb-77a2-4153-b7da-1f7c115b2ff2",
      "name": "profile-picture.jpg",
      "size": 245678,
      "bucketId": "users-bucket",
      "etag": "\"a1b2c3d4e5f6\"",
      "createdAt": "2023-01-15T12:34:56Z",
      "updatedAt": "2023-01-16T09:45:32Z",
      "isUploaded": true,
      "mimeType": "image/jpeg",
      "uploadedByUserId": "abc123def456",
      "metadata": {
        "alt": "Profile picture",
        "category": "avatar"
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API key to authorize requests.

Body

multipart/form-data

File upload data including files and optional metadata

​
file[]
file[]
required

Array of files to upload.

​
bucket-id
string

Target bucket identifier where files will be stored.

Example:

"user-uploads"

​
metadata[]
object[]

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

Response

Files successfully uploaded

​
processedFiles
object[]
required

List of successfully processed files with their metadata.