Create File
The Create File operation creates a new file or replaces a file. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. When you call Create File, you only initialize the file. To add content to a file, you call the Put Range operation.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS | |
Request
The Create File request is constructed as follows. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Replace the path components that are shown in the request URI with your own, as described in the following table:
| Path component | Description |
|---|---|
myaccount |
The name of your storage account. |
myshare |
The name of your file share. |
mydirectorypath |
Optional. The path to the directory where the file is to be created. If the directory path is omitted, the file is created within the specified share. If the directory is specified, it must already exist within the share before you can create the file. |
myfile |
The name of the file to create. |
For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.
URI parameters
You can specify the following additional parameters on the request URI:
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for file service operations. |
Request headers
The required and optional request headers are described in the following tables:
Common request headers
| Request header | Description |
|---|---|
Authorization |
Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage. |
Date or x-ms-date |
Required. Specifies the Coordinated Universal Time (UTC) time for the request. For more information, see Authorize requests to Azure Storage. |
x-ms-version |
Required for all authorized requests. Specifies the version of the operation to use for this request. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. For more information, see Versioning for the Azure Storage services. |
Content-Length |
Optional. Must be zero if present. |
x-ms-content-length: byte value |
Required. This header specifies the maximum size for the file, up to 4 tebibytes (TiB). |
Content-Type or x-ms-content-type |
Optional. The MIME content type of the file. The default type is application/octet-stream. |
Content-Encoding or x-ms-content-encoding |
Optional. Specifies which content encodings have been applied to the file. This value is returned to the client when the Get File operation is performed on the file resource, and you can use it to decode file content. |
Content-Language or x-ms-content-language |
Optional. Specifies the natural languages that are used by this resource. |
Cache-Control or x-ms-cache-control |
Optional. Azure Files stores this value but doesn't use or modify it. |
x-ms-content-md5 |
Optional. Sets the file's MD5 hash. |
x-ms-content-disposition |
Optional. Sets the file's Content-Disposition header. |
x-ms-type: file |
Required. Set this header to file. |
x-ms-meta-name:value |
Optional. Name-value pairs that are associated with the file as metadata. Metadata names must adhere to the naming rules for C# identifiers. Note: File metadata that's specified via Azure Files isn't accessible from a Server Message Block (SMB) client. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. The Coordinated Universal Time (UTC) creation time property for the file. A value of now can be used to indicate the time of the request. The default value is now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. The Coordinated Universal Time (UTC) last write property for the file. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-lease-id:<ID> |
Required if the file has an active lease. Available for version 2019-02-02 and later. This header is ignored if the file is located on a File Share with NFS protocol enabled, which doesn't support file leases. |
x-ms-client-request-id |
Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Files. |
x-ms-file-request-intent |
Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they're included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later. |
x-ms-allow-trailing-dot: { <Boolean> } |
Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. This header is ignored if the target is located on a File Share with NFS protocol enabled, which supports trailing dot by default. For more information, see Naming and referencing shares, directories, files, and metadata. |
SMB only request headers
| Request header | Description |
|---|---|
x-ms-file-change-time: { now ¦ <DateTime> } |
Optional. Version 2021-06-08 and later. The Coordinated Universal Time (UTC) change time property for the file, in the ISO 8601 format. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } |
In version 2019-02-02 through 2021-04-10, this header is required if x-ms-file-permission-key isn't specified. As of version 2021-06-08, both headers are optional. This permission is the security descriptor for the file that's specified in the Security Descriptor Definition Language (SDDL) or (version 2024-11-04 or later) in base64-encoded binary security descriptor format. You can specify which format to use with the x-ms-file-permission-format header. You can use this header if the permissions size is 8 kibibytes (KiB) or less. Otherwise, you can use x-ms-file-permission-key. If you specify the header, it must have an owner, group, and discretionary access control list (DACL). You can pass a value of inherit to inherit from the parent directory. |
x-ms-file-permission-format: { sddl ¦ binary } |
Optional. Version 2024-11-04 or later. Specifies whether the value passed in x-ms-file-permission is in SDDL or in binary format. If x-ms-file-permission-key is set to inherit, this header shouldn't be set. If x-ms-file-permission-key is set to any other value than inherit, and if this header isn't set, the default value of sddl is used. |
x-ms-file-permission-key: <PermissionKey> |
In version 2019-02-02 through 2021-04-10, this header is required if x-ms-file-permission isn't specified. As of version 2021-06-08, both headers are optional. If neither header is specified, the default value of inherit is used for the x-ms-file-permission header.You can create the key by calling the Create Permission API. |
x-ms-file-attributes |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. This header contains the file system attributes to be set on the file. For more information, see the list of available attributes. The default value is None. |
NFS only request headers
| Request header | Description |
|---|---|
x-ms-mode |
Optional. Version 2025-05-05 and later. The mode bits to be set on the file. Mode is represented in the 12-bit numeric octal format or the symbolic 'rwx' format. The default value is 0644. See POSIX file permissions (mode). |
x-ms-owner |
Optional. Version 2025-05-05 and later. The user identifier (UID) of the file owner to be set on the file. The default value is 0 (root). |
x-ms-group |
Optional. Version 2025-05-05 and later. The group identifier (GID) of the file owner to be set on the file. The default value is 0 (root group). |
x-ms-file-file-type |
Optional. Version 2025-05-05 and later. The type of the file. Must be 'Regular' if present. |
Request body
None.
Sample request
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1
Request Headers:
x-ms-version: 2020-02-10
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT
Content-Type: text/plain; charset=UTF-8
x-ms-content-length: 1024
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Response
The response includes an HTTP status code and a set of response headers.
Status code
A successful operation returns status code 201 (Created). For information about status codes, see Status and error codes.
Response headers
The response for this operation includes the headers in the following tables. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
Common response headers
| Response header | Description |
|---|---|
ETag |
The ETag contains a value that represents the version of the file. The value is enclosed in quotation marks. |
Last-Modified |
Returns the date and time when the file was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers. Any operation that modifies the directory or its properties updates the last modified time. Operations on files don't affect the last modified time of the directory. |
x-ms-request-id |
Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshoot API operations |
x-ms-version |
Indicates the Azure Files version that's used to execute the request. |
Date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
x-ms-request-server-encrypted: true/false |
Version 2017-04-17 and later. The value of this header is set to true if you have successfully encrypted the contents of the request by using the specified algorithm. If the encryption is unsuccessful, the value is false. |
x-ms-file-creation-time |
The UTC date/time value that represents the creation time property for the file. |
x-ms-file-last-write-time |
The UTC date/time value that represents the last write time property for the file. |
x-ms-file-change-time |
The UTC date/time that value that represents the change time property for the file. |
x-ms-file-file-id |
The file ID of the file. |
x-ms-file-parent-id |
The parent file ID of the file. |
x-ms-client-request-id |
Used to troubleshoot requests and their corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it isn't present in the response. |
SMB only response headers
| Response header | Description |
|---|---|
x-ms-file-permission-key |
Version 2019-02-02 and later. The key of the permission of the file. |
x-ms-file-attributes |
Version 2019-02-02 and later. The file system attributes of the file. For more information, see the list of available attributes. |
NFS only response headers
| Response header | Description |
|---|---|
x-ms-mode |
Version 2025-05-05 and later. The mode of the file. See POSIX file permissions (mode). |
x-ms-owner |
Version 2025-05-05 and later. The user identifier (UID) of the file owner. |
x-ms-group |
Version 2025-05-05 and later. The group identifier (GID) of the file owner. |
x-ms-file-file-type |
Version 2025-05-05 and later. The type of the file, the possible value is: 'Regular'. |
Response body
None.
Sample response
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Date: Mon, 27 Jan 2014 23:00:12 GMT
ETag: "0x8CB14C3E29B7E82"
Last-Modified: Mon, 27 Jan 2014 23:00:06 GMT
x-ms-version: 2014-02-14
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Authorization
Only the account owner can call this operation.
File system attributes
| Attribute | Win32 file attribute | Definition |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | A file that's read-only. Applications can read the file, but they can't write to it or delete it. |
| Hidden | FILE_ATTRIBUTE_HIDDEN | The file is hidden. It isn't included in an ordinary directory listing. |
| System | FILE_ATTRIBUTE_SYSTEM | A file that the operating system uses a part of, or uses exclusively. |
| None | FILE_ATTRIBUTE_NORMAL | A file that doesn't have other attributes set. This attribute is valid only when used alone. |
| Archive | FILE_ATTRIBUTE_ARCHIVE | A file that's an archive file. Applications ordinarily use this attribute to mark files for backup or removal. |
| Temporary | FILE_ATTRIBUTE_TEMPORARY | A file that's being used for temporary storage. |
| Offline | FILE_ATTRIBUTE_OFFLINE | The data of a file isn't available immediately. This file system attribute is presented primarily to provide compatibility with Windows. Azure Files doesn't support it with offline storage options. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | The file isn't to be indexed by the content indexing service. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | The user data stream that's not to be read by the background data integrity scanner. This file system attribute is presented primarily to provide compatibility with Windows. |
POSIX file permissions (mode)
POSIX file permissions can be specified either numerically in a 12-bit numeric octal format or in a symbolic "rwx" format. Examples:
- "0644" or "rw-r--r--": User (file owner) has read, write permission. Group has read permission. Others have read permission.
- "0755" or "rwxr-xr-x": User (file owner) has read, write, and execute permission. Group has read and execute permission. Others have read and execute permission.
Numeric octal format
The three lowest order octal numbers represent the permissions for owner/user, group, and others and are indicated using an octal number (0-7), formed using a bitwise combination of '4' (Read), '2' (Write), '1' (Execute). The highest order octal number (0-7) is used to indicate a combination of '4' (SetUID), '2' (SetGID), '1' (StickyBit) permissions.
| Format | Permission |
|---|---|
| 0700 | User (file owner) has read, write, and execute permission. |
| 0400 | User has read permission. |
| 0200 | User has write permission. |
| 0100 | User has execute permission. |
| 0070 | Group has read, write, and execute permission. |
| 0040 | Group has read permission. |
| 0020 | Group has write permission. |
| 0010 | Group has execute permission. |
| 0007 | Others have read, write, and execute permission. |
| 0004 | Others have read permission. |
| 0002 | Others have write permission. |
| 0001 | Others have execute permission. |
| 4000 | Set effective user ID on file. |
| 2000 | Set effective group ID on file. |
| 1000 | Set to indicate that the file can be deleted or renamed only by file owner, directory owner, or root user. |
Symbolic "rwx" format
Permissions for owner/user, group, and others are indicated using a combination of 'r' (Read), 'w' (Write), and 'x' (Execute) characters.
| Format | Permission |
|---|---|
| rwx------ | User (file owner) has read, write, and execute permission. |
| r-------- | User has read permission. |
| -w------- | User has write permission. |
| --x------ | User has execute permission. |
| ---rwx--- | Group has read, write, and execute permission. |
| ---r----- | Group has read permission. |
| ----w---- | Group has write permission. |
| -----x--- | Group has execute permission. |
| ------rwx | Others have read, write, and execute permission. |
| ------r-- | Others have read permission. |
| -------w- | Others have write permission. |
| --------x | Others have execute permission. |
Remarks
To create a new file, first initialize it by calling Create File and specifying its maximum size, up to 4 TiB. When you're performing this operation, don't include content in the request body. After you've created the file, call Put Range to add content to the file or to modify it.
You can change the size of the file by calling Set File Properties.
If the share or parent directory doesn't exist, then the operation fails with status code 412 (Precondition Failed).
Note
The file properties cache-control, content-type, content-md5, content-encoding, and content-language are separate from the file system properties that are available to SMB clients. SMB clients are unable to read, write, or modify these property values.
To create the file, if the existing file has an active lease, the client must specify a valid lease ID on the request. If the client either doesn't specify a lease ID or specifies an invalid lease ID, Azure Files returns status code 412 (Precondition Failed). If the client specifies a lease ID but the file doesn't have an active lease, Azure Files returns status code 412 (Precondition Failed) in this instance also. If the client specifies a lease ID on a file that doesn't yet exist, Azure Files returns status code 412 (Precondition Failed) for requests that are made against version 2019-02-02 and later.
If an existing file with an active lease is overwritten by a Create File operation, the lease persists on the updated file until it's released.
Create File isn't supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot fails with status code 400 (InvalidQueryParameterValue).