Docs

Torch Object Storage

Symbolic Link

PutSymlink

Description

Use the PutSymlink API to create a symbolic link for an existing target file in TOS, allowing you to quickly access the target file through this link.

Precautions

The PutSymlink API charges requests based on the storage type of the symlink object. For detailed information, see Request Count Charges.

When creating a symbolic link using the PutSymlink API, it does not verify whether the target file exists or if you have permission to access it. When calling APIs such as GetObject and HeadObject to obtain symbolic link information, the system checks whether your account has read permissions for both the symlink and the target file, and whether the target file exists.

Both the symbolic link object and target object can be located in different storage buckets within the same region but do not support storage buckets in different regions.

Nested symbolic links are not supported. You can use the PutSymlink interface to create secondary links, but you cannot access the target file through the secondary symlink.

For more notes on the PutSymlink interface, see Create Symbolic Link.

Request syntax

tip

In the request message style, ObjectName specifies the name of the soft link, and bucketname in Host specifbucketname in Host specifies the bucket name storing the soft link.

Request parameters and headers

This request uses the public request header, see Common Parameters.

Name	Location	Type	Required	Sample Value	Description
symlink	Query	String	Yes	-	Represents a special identifier for the PutSymlink request.
x-tos-symlink-target	Header	String	Yes	test-object	Target file name pointed to by the symbolic link. The target file name must be URL-encoded according to the application/x-www-form-urlencoded standard. The target file pointed to by a symbolic link cannot be another symbolic link.
x-tos-symlink-bucket	Header	String	No	test-bucket	The storage bucket of the target file pointed to by the symbolic link. If not set, it means the symbolic link and its target file are within the same bucket.
x-tos-forbid-overwrite	Header	String	No	false	If an object with the same name exists in the bucket, whether to allow the symlink to overwrite that object is explained as follows: true: prohibits overwriting objects with the same name. false: allows overwriting objects with the same name. Default is false, which means if the x-tos-forbid-overwrite parameter is not set, overwriting objects with the same name is allowed. When the bucket owning the symbolic link is in versioning enabled or suspended state, the x-tos-forbid-overwrite parameter is invalid, allowing overwriting objects with the same name.
x-tos-acl	Header	String	No	private	Access permissions for symbolic links, valid settings include: private: private public-read: public read public-read-write: public read-write authenticated-read: authenticated user read bucket-owner-read: bucket owner read bucket-owner-full-control: bucket owner full control. bucket-owner-entrusted: controlled by bucket policy, the bucket owner has full control. default: inherits bucket ACL, meaning the object's ACL policy aligns with the bucket's ACL policy. default is private.
x-tos-storage-class	Header	String	No	STANDARD	The storage types for soft links.For detailed information, please refer to Storage type. If not set, it defaults to the storage type of the bucket it belongs to. tip Storage classes such as Infrequent Access Storage and Flashback Archive have a minimum billing unit. For individual files smaller than 64 KiB, storage capacity charges will be calculated as if they were 64 KiB. In contrast, for the Standard storage class, small objects (less than 64 KiB) are billed based on their actual size, provided that the total number of such small objects in a given region is fewer than 1 billion. Since symbolic link objects typically occupy less than 64 KiB, we recommend setting their storage class to Standard to avoid unnecessary charges.
x-tos-tagging	Header	String	No	Key1=Value1&Key2=Value	The target tag information of the symbolic link, in the format {Key}={Value}. Multiple tags can be set simultaneously, separated by & when setting multiple tags. Object tag keys and values must be URL-encoded according to the application/x-www-form-urlencoded standard. If a tag does not use = to set a value, TOS treats the tag’s value as an empty string. For more restrictions on object tags, see Object Tags.
x-tos-meta-*	Header	String	No	x-tos-meta-key:value	Custom metadata of symbolic links.

Request body elements

There is no request message element in this request.

Response headers

This request returns the common response message headers, please see Common Parameters.

Name	Type	Sample value	Description
x-tos-version-id	String	5840E600C6FBD446792D	Version number of the symbolic link. If no version number exists, the message header will not appear in the response message.

Response body elements

There is no message element in this request response.

Sample request

Sample response

Last updated: 2025.11.10 10:48:45