Create Directory
The Create Directory
operation creates a new directory under the specified share or parent directory. The directory resource includes the properties for that directory. It doesn't include a list of the files or subdirectories contained by the directory. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled.
Enabled file share protocol | Available |
---|---|
SMB | ![]() |
NFS | ![]() |
The Create Directory
request is constructed as follows. We recommend that you use HTTPS.
Method | Request URI | HTTP version |
---|---|---|
PUT | https://myaccount.file.core.windows.net/myshare/myparentdirectorypath/mydirectory?restype=directory |
HTTP/1.1 |
Replace the path components in the request URI with your own, as shown in the following table:
Path component | Description |
---|---|
myaccount |
The name of your storage account. |
myshare |
The name of your file share. |
myparentdirectorypath |
Optional. The path to the parent directory where mydirectory is to be created. If the parent directory path is omitted, the directory is created within the specified share. If the parent directory is specified, it must already exist within the share before you can create mydirectory. |
mydirectory |
The name of the directory to create. |
For more information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.
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. |
The required and optional request headers are described in the following tables:
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. |
x-ms-meta-name:value |
Optional. Version 2015-02-21 or later. A name-value pair to associate with the directory as metadata. Metadata names must adhere to the naming rules for C# identifiers. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Required: version 2019-02-02 to 2021-04-10. Optional: version 2021-06-08 and newer. The Coordinated Universal Time (UTC) creation time property for the directory. You can use a value of now 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 or later. The Coordinated Universal Time (UTC) last write property for the directory. You can use a value of now to indicate the time of the request. The default value is now . |
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. |
Request header | Description |
---|---|
x-ms-file-change-time: { now ¦ <DateTime> } |
Optional. The Coordinated Universal Time (UTC) change time property for the directory, in the ISO 8601 format. Version 2021-06-08 and newer. 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 directory 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. This header can be used if the permissions size is over 8 kibibytes (KiB). Otherwise, you can use x-ms-file-permission-key . If it's specified, 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.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key . If neither header is specified, the default value of inherit is used. |
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> |
The key of the permission to be set for the directory. 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. You can create this key by using the Create-Permission API.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key . If neither header is specified, the default value of inherit is used for the x-ms-file-permission header. |
x-ms-file-attributes |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. The file system attributes to be set on the directory. See the list of available attributes. The default value is Directory. |
Request header | Description |
---|---|
x-ms-mode |
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 0755. See POSIX file permissions (mode). See POSIX file permissions (mode). |
x-ms-owner |
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 |
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). |
None.
PUT https://myaccount.file.core.windows.net/myshare/myparentdirectorypath/mydirectory? restype=directory HTTP/1.1
Request headers:
x-ms-version: 2014-02-14
x-ms-date: Mon, 27 Jan 2014 22:50:32 GMT
x-ms-meta-Category: Images
Authorization: SharedKey myaccount:Z5043vY9MesKNh0PNtksNc9nbXSSqGHueE00JdjidOQ=
The response includes an HTTP status code and a set of response headers.
A successful operation returns status code 201 (Created). For more information about status codes, see Status and error codes.
The response for this operation includes the headers in the following tables. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
Response header | Description |
---|---|
ETag |
Contains a value that represents the version of the directory, enclosed in quotation marks. |
Last-Modified |
Returns the date and time when the directory 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 was 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 or later. The value of this header is set to true if the contents of the request are successfully encrypted using the specified algorithm, and false otherwise. |
x-ms-file-creation-time |
The UTC date/time value that represents the creation time property for the directory. |
x-ms-file-last-write-time |
The UTC date/time value that represents the last write time property for the directory. |
x-ms-file-change-time |
The UTC date/time that value that represents the change time property for the directory. |
x-ms-file-file-id |
The file ID of the directory. |
x-ms-file-parent-id |
The parent file ID of the directory. |
x-ms-client-request-id |
Can be used to troubleshoot requests and 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 1024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, this header isn't present in the response. |
Response header | Description |
---|---|
x-ms-file-permission-key |
Version 2019-02-02 and later. The key of the permission of the directory. |
x-ms-file-attributes |
Version 2019-02-02 and later. The file system attributes on the directory. For more information, see the list of available attributes. |
Response header | Description |
---|---|
x-ms-mode |
Version 2025-05-05 and later. The mode of the directory. See POSIX file permissions (mode). |
x-ms-owner |
Version 2025-05-05 and later. The user identifier (UID) of the directory owner. |
x-ms-group |
Version 2025-05-05 and later. The group identifier (GID) of the directory owner. |
x-ms-file-file-type |
Version 2025-05-05 and later. The type of the file, the possible value is: Directory . |
None.
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
Only the account owner may call this operation.
Attribute | Win32 file attribute | Definition |
---|---|---|
ReadOnly | FILE_ATTRIBUTE_READONLY | A directory that's read-only. |
Hidden | FILE_ATTRIBUTE_HIDDEN | The directory is hidden. It isn't included in an ordinary directory listing. |
System | FILE_ATTRIBUTE_SYSTEM | A directory that the operating system uses a part of, or uses exclusively. |
None | FILE_ATTRIBUTE_NORMAL | A directory that doesn't have other attributes set. This attribute is valid only when it's used alone. |
Directory | FILE_ATTRIBUTE_DIRECTORY | The handle that identifies a directory. |
Archive | FILE_ATTRIBUTE_ARCHIVE | A directory that's an archive directory. Applications ordinarily use this attribute to mark files for backup or removal. |
Offline | FILE_ATTRIBUTE_OFFLINE | The data of a directory 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 directory 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 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.
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. |
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. |
If a directory by the same name is being deleted when Create Directory
is called, the server returns status code 409 (Conflict), and it provides additional error information that indicates that the directory is being deleted.
If a directory or file with the same name already exists, the operation fails with status code 409 (Conflict). If the parent directory doesn't exist, the operation fails with status code 412 (Precondition Failed).
It isn't possible to create a directory hierarchy with a single Create Directory
operation. You can create the directory only if its immediate parent already exists, as specified in the path. If the parent directory doesn't exist, the operation fails with status code 412 (Precondition Failed).
Create Directory
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 400 (InvalidQueryParameterValue)