Skip to content
Nhost Documentation
Support Dashboard

Replace file

PUT
/files/{id}

Replace an existing file with new content while preserving the file ID. The operation follows these steps:

  1. The isUploaded flag is set to false to mark the file as being updated
  2. The file content is replaced in the storage backend
  3. File metadata is updated (size, mime-type, isUploaded, etc.)

Each step is atomic, but if a step fails, previous steps will not be automatically rolled back.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Unique identifier of the file to replace

Request Body required

Section titled “Request Body required ”

File replacement data including new file content and optional metadata

object
metadata

Metadata that can be updated for an existing file.

object
name

New name to assign to the file.

string
Example
renamed-file.jpg
metadata

Updated custom metadata to associate with the file.

object
key
additional properties
any
Example
{
  "alt": "Updated image description",
  "category": "profile"
}
file

New file content to replace the existing file

string format: binary

Responses

Section titled “ Responses ”

200

Section titled “200 ”

File successfully replaced

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 file replacement

Error information returned by the API.

object
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