All Products
Search

This Product

    Object Storage Service:PutSymlink

    Document Center

    Object Storage Service:PutSymlink

    Last Updated:Jun 02, 2026

    Creates a symbolic link (symlink) that points to a destination object in OSS. You can use the symlink to access the destination object.

    Usage notes

    • PutSymlink does not validate whether the destination object exists, whether its storage class is valid, or whether you have access to it.

    • The ACL of the symlink and the destination object are checked only when operations such as GetObject access the destination object.

    • Request headers prefixed with x-oss-meta- are stored as user metadata of the symlink. Example: x-oss-meta-location. You can specify multiple metadata headers, but total metadata size cannot exceed 8 KB.

    • By default, if an object with the same name exists and you have access permissions, the new object overwrites the existing one. OSS returns 200 OK.

    Versioning

    A symlink points to the current version of the destination object.

    A symlink can have multiple versions, each pointing to a different object. OSS generates version IDs and returns them in the x-oss-version-id response header.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    PutSymlink

    oss:PutObject

    Creates a symbolic link for an object.

    oss:PutObjectTagging

    When creating a symbolic link for an object, if you specify object tags through x-oss-tagging, this permission is required.

    Request syntax

    PUT /ObjectName?symlink HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-symlink-target: TargetObjectName

    Request headers

    Header

    Type

    Required

    Description

    x-oss-forbid-overwrite

    String

    No

    Specifies whether to prevent overwriting an existing object with the same name.

    • Not specified or set to false: the existing object is overwritten.

    • Set to true: the existing object cannot be overwritten.

    Specifying this header may degrade QPS performance. If your QPS exceeds 1,000, contact technical support.

    Note

    This header does not take effect when versioning is enabled or suspended for the bucket. PutSymlink overwrites the object regardless.

    x-oss-symlink-target

    String

    Yes

    The destination object to which the symbolic link points.

    Follows the same naming conventions as objects.

    • TargetObjectName must be URL-encoded, same as ObjectName.

    • The destination object cannot be a symbolic link.

    x-oss-object-acl

    String

    No

    The ACL of the object. Default value: default.

    Valid values:

    • default: Inherits the bucket ACL.

    • private: Only the owner and authorized users can read and write the object.

    • public-read: All users can read the object. Only the owner and authorized users can write. Use with caution.

    • public-read-write: All users can read and write the object. Use with caution.

    For more information about object ACLs, see Object ACLs.

    x-oss-storage-class

    String

    No

    The storage class of the object.

    If specified, overrides the bucket's default storage class. For example, setting this to Standard when uploading to an IA bucket stores the object as Standard.

    Valid values:

    • Standard

    • IA

    • Archive

    IA and Archive objects have a minimum billable size of 64 KB. Avoid setting storage class to IA or Archive for symlinks.

    Storage class details: Overview.

    For more information about the common request headers included in a PutSymlink request, such as Host and Date, see Common request headers.

    Response headers

    The response to a PutSymlink request contains only common response headers. For more information, see Common response headers.

    Examples

    • Sample requests 

      PUT /link-to-oss.jpg?symlink HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Cache-control: no-cache 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Tue, 08 Nov 2016 02:00:25 GMT 
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
x-oss-symlink-target: oss****
x-oss-storage-class: Standard

      Sample success responses 

      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: "0A477B89B4602AA8DECB8E19BFD4****"

    • Sample requests for a versioned bucket 

      PUT /link-to-oss.jpg?symlink HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Tue, 09 Apr 2019 06:50:48 GMT 
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-symlink-target: oss.jpg

      Sample success responses 

      HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 06:50:48 GMT
Content-Length: 0
Connection: keep-alive
x-oss-version-id: CAEQNRiBgMClj7qD0BYiIDQ5Y2QyMjc3NGZkODRlMTU5M2VkY2U3MWRiNGRh****
x-oss-request-id: 5CAC40C8B7AEADE01700064B
ETag: "136A5E127272200EDAB170DD84DE****"

    OSS SDKs

    The following OSS SDKs support PutSymlink:

    ossutil

    For information about the ossutil command that corresponds to the PutSymlink operation, see put-symlink.

    Error codes

    Error code

    HTTP status code

    Description

    InvalidArgument

    400

    The StorageClass value is invalid.

    FileAlreadyExists

    409

    An object with the same name exists and x-oss-forbid-overwrite is set to true.

    FileImmutable

    409

    The object is protected by a retention policy.