# IRPCObjectOperations.UploadFile

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/

Badges: `Vault API / core` `write` `session or assertion` `idempotent`

Uploads a block of new content for an existing file of an object that is checked out to the
caller.

- **Service:** [Objects, versions, properties and files](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md) `MFiles.IRPCObjectOperations`
- **gRPC method:** `/MFiles.IRPCObjectOperations/UploadFile`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upload-file`
- **Request:** [`UploadFileRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md#request)
- **Response:** [`UploadFileResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFile/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

Works like [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): the first call has
`upload_id` 0 and `offset` 0, later calls pass the returned `upload_id`. Complete the upload with
[UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md), which replaces the
content of the file. To create a new object with files, use `UploadTempFile` and
[AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md) instead.

<a id="request"></a>

## Request: UploadFileRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | 0 to start a new upload; the returned ID for the following blocks. |
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object that owns the file. |
| `obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_id.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id.item_id.external_repository_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
| `file` | [`File`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.File/index.md) | The file to replace, as returned for the checked-out version: at least `file_ver`, and the new `size` with `size_precision` `FILE_SIZE_PRECISION_EXACT`. |
| `file.file_ver` | [`FileVer`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileVer/index.md) | The file and its version. Pass it unchanged in an `ObjFileVer` to download the file. |
| `file.file_ver.file_id` | [`FileID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileID/index.md) | The file. |
| `file.file_ver.type` | [`FileVerType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileVerType/index.md) | `FILE_VER_TYPE_SPECIFIC` for a file version number. Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3). |
| `file.file_ver.internal_version` | `int32` | The file version number. |
| `file.file_ver.external_repository_version` | `string` | Used only for files in external repositories. Leave empty. |
| `file.file_ver.external_repository_sort_key` | `int64` | Used only for files in external repositories. Leave 0. |
| `file.title` | `string` | The file name without the extension. |
| `file.extension` | `string` | The file name extension without the dot, for example "pdf". |
| `file.size` | `int64` | The size of the file in bytes. Exact when `size_precision` is `FILE_SIZE_PRECISION_EXACT`. |
| `file.size_precision` | [`FileSizePrecision`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileSizePrecision/index.md) | How exact `size` is. Do not rely on `size` if it is `FILE_SIZE_PRECISION_UNKNOWN`. Values: `FILE_SIZE_PRECISION_EXACT` (0), `FILE_SIZE_PRECISION_ESTIMATE` (1), `FILE_SIZE_PRECISION_UNKNOWN` (2). |
| `file.created_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was originally created. |
| `file.accessed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last accessed (e.g. read). |
| `file.written_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to. |
| `file.changed_at_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The time in UTC the file was last written to or its attributes were changed. |
| `file.guid` | `string` | GUID of the file. |
| `file.md5_checksum` | `string` | The MD5 checksum of the file as 32 lowercase hexadecimal digits, if available. |
| `file.is_missing` | `bool` | True, if the file is missing. |
| `file.is_content_volatile` | `bool` | True, if the file physical content is volatile. I.e. the physical content can change without the version number change, as long as the logical content is same. The file content is guaranteed to stay physically consistent within single download session only. |
| `file.flags` | [`OBJECTFILEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJECTFILEFLAGS/index.md) | Object file flags. |
| `file.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `file.flags.can_be_edited_externally` | `bool` | Next available value. |
| `file.master_storage_file_ref` | `string` | An optional File reference (GUID) to external Master Storage API. Only used with Master Storage, otherwise empty. |
| `offset` | `int64` | The position of this block in the file. Must be 0 in the first call. Use multiples of 4096 bytes for all blocks but the last. |
| `data` | `bytes` | The bytes of this block. |

<a id="response"></a>

## Response: UploadFileResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `upload_id` | `int32` | Receives the identifier of this upload operation. |

<a id="related"></a>

## Related methods

- [UploadTempFile](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadTempFile/index.md): Uploads a block of a file to a temporary upload session on the server. The upload can then be used as the content of a new object.
- [UploadFileCommit](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/UploadFileCommit/index.md): Completes an upload made with UploadFile and stores it as the new content of the file.
- [AddObjectWithFiles](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObjectWithFiles/index.md): Creates a new object, optionally with its files, and optionally checks it in.