# IRPCFileTransfer.FileUploadBegin

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) > [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md)

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

Badges: `Vault API / standard` `write` `session or assertion`

Begins an upload in blocks and returns its `file_ref` and the block rules.

- **Service:** [Stateless file upload sessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/index.md) `MFiles.IRPCFileTransfer`
- **gRPC method:** `/MFiles.IRPCFileTransfer/FileUploadBegin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/file-upload-begin`
- **Request:** [`FileUploadBeginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md#request)
- **Response:** [`FileUploadBeginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadBegin/index.md#response)
- **Book and level:** Vault API, standard
- **Kind:** write
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

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

## Remarks

Upload the blocks with
[FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md), each at most
`max_block_size` bytes; all blocks but the last must be exactly `max_block_size` bytes when
`require_sequential_blocks` is true. Then call
[FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md).

A file has at most 50,000 blocks. If `total_size_in_bytes` is larger than 50,000 times the
maximum block size, the call fails with `ERROR_FILE_TOO_LARGE`. Event handlers of the vault can
cancel the upload here; the call then fails with their error.

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

## Request: FileUploadBeginRequest

> 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 |
|---|---|---|
| `total_size_in_bytes` | `int64` | The size of the whole file in bytes, if known; 0 if not. If set, the ended upload must have exactly this size. |

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

## Response: FileUploadBeginResponse

> 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 |
|---|---|---|
| `file_ref` | `string` | Identifies the upload in `FileUploadBlock`, `FileUploadEnd`, `FileUploadAttach` and the other methods that take an uploaded file. |
| `max_block_size` | `int64` | The maximum size of one block in bytes. |
| `require_sequential_blocks` | `bool` | True if the blocks must be uploaded in order, one at a time, and every block but the last must be `max_block_size` bytes. False if blocks can be uploaded in any order and concurrently, also through different server instances. |

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

## Related methods

- [IRPCFileTransferStreaming.FileUploadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransferStreaming/FileUploadBlock/index.md): Uploads one block of a stateless file upload by streaming its data.
- [FileUploadEnd](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCFileTransfer/FileUploadEnd/index.md): Completes an upload in blocks. Binds the content to no object; use FileUploadAttach or AddObjectWithFiles for that.