Creates a symbol link directing to the target object. You can use the symbol link to access the target object.

Request syntax

PUT /ObjectName?symlink HTTP/1.1
Date: GMT Date
Authorization: SignatureValue
x-oss-symlink-target: TargetObjectName

Request headers

Header Type Required Description
x-oss-symlink-target String Yes Indicates the target object that the symbolic link directs to.

Valid value: The naming conventions are the same as those for objects.

  • Similar to ObjectName, TargetObjectName must be URL-encoded.
  • The target object that a symbolic link directs to cannot be a symbolic link.
x-oss-storage-class String No Specifies the storage class of the target object.
Valid values:
  • Standard
  • IA
  • Archive

Supported APIs: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

  • We recommend that you do not set the storage class in PutObjectSymlink to IA or Archive because an IA or Archive object smaller than 64 KB is billed at 64 KB.
  • If you specify the value of x-oss-storage-class when uploading an object to a bucket, the storage class of the uploaded object is the specified value of x-oss-storage-class regardless of the storage class of the bucket. For example, if you specify the value of x-oss-storage-class to Standard when uploading an object to a bucket of the IA storage class, the storage class of the object is Standard.

Detail analysis

  • When a symbolic link is created, the following checks are not performed:
    • Whether the target object exists.
    • Whether the storage class of the target object is valid.
    • Whether the user has permission to access the target object.

    These checks are performed by APIs that access the target object, such as GetObject.

  • If the object that you want to add already exists and you can access the object, the existing object is overwritten by the added object and a 200 OK message is returned.
  • If a PutSymlink request carries a parameter with the x-oss-meta- prefix, the parameter is considered as user meta, such as x-oss-meta-location. An object can have multiple parameters with the x-oss-meta- prefix. However, the total size of all user meta cannot exceed 8 KB.


Request example:

PUT /link-to-oss.jpg? symlink HTTP/1.1 
Cache-control: no-cache 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Tue, 08 Nov 2016 02:00:25 GMT 
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2PRrk= x-oss-symlink-target: oss.jpg
x-oss-storage-class: Standard

Response example:

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 08 Nov 2016 02:00:25 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 582131B9109F4EE66CDE56A5
ETag: "0A477B89B4602AA8DECB8E19BFD447B6"


The SDKs of this API are as follows:

Error codes

Error code HTTP status code Description
InvalidArgument 400 The value of x-oss-storage-class is invalid.