Create a symlink
Updated at：2025-11-03
API description
The PutSymlink API is used to create a symlink for an existing target object (referred to as the "target object" in this document) within the same bucket. Access to the target object is available via the symlink.
Note:
- The symlink file and its target object must reside in the same bucket.
- Symlinks can now be created for object files in standard storage, infrequent access storage, cold storage, and archive storage. However, symlink files do not support the ARCHIVE storage class. If the ARCHIVE class is specified or omitted while the bucket's default storage class is ARCHIVE, a CODE_INVALID_ARGUMENT error will be returned.
- When this API is called to create a symlink, it does not verify whether the target file exists or whether there is permission to access it. However, when the GetObject API is called via the symlink, it checks if the user has read permission for both the symlink and the target file, as well as whether the target file exists.
- Creating a symlink requires the appropriate write permission.
- If the "x-bce-forbid-overwrite" header is not specified, and there is an object file which has the same name as the symlink file, the same-named object will be overwritten by default during symlink creation.
- Secondary symlinks are not supported. While no checks are performed when creating a secondary symlink, users will not be able to access the target object data through it.
Request URI
PUT /v1/{bucketName}/{objectKey}?symlink
Request header parameters
| Parameter name | Parameter type | Required or not | Description | Example value |
|---|---|---|---|---|
| xBceSymlinkTarget | String | Yes | The naming rules for the target file of a symlink are the same as those for objects. However, the target file of a symlink cannot itself be a symlink file. | "xBceSymlinkTarget_example" |
| xBceForbidOverwrite | String | No | Specify whether to overwrite an object with the same name when creating a symlink. By default, if x-bce-forbid-overwrite is not specified, overwriting is allowed. If set to true, overwriting is prohibited; if set to false, overwriting is allowed. | "xBceForbidOverwrite_example" |
| xBceMeta_ | String | No | User-defined meta | "xBceMeta__example" |
| xBceStorageClass | String | No | Specify the storage class for the symlink file. STANDARD represents standard storage, STANDARD_IA represents infrequent access storage, and COLD represents cold storage. If not specified, the symlink file will default to the bucket's storage class. Symlink files are not compatible with the ARCHIVE storage class. | "xBceStorageClass_example" |
Parameters of request body
None
Response header parameters
| Parameter name | Parameter type | Description | Example value |
|---|---|---|---|
| ETag | String | The HTTP protocol entity tag of symlink target object |
Response body parameters
None
Request example
None
Response example
JSON
1HTTP/1.1 200 OK
2 <Common response headers>
3{ }Error code
Please refer to the general error codes