PUT Object Copy

The PUT Object Copy operation creates a copy of a stored S3 object. A PUT Object Copy operation is the same as performing a GET and then a PUT. Adding the request header, x-amz-copy-source, makes the PUT operation copy the source object into the destination bucket. When copying an object, you can preserve most of the metadata (default) or specify new metadata. However, the ACL is not preserved and is set to private for the user making the request. All copy requests must be authenticated and cannot contain a message body. Additionally, you must have READ access to the source object and WRITE access to the destination bucket. To copy an object only under certain conditions, such as whether the ETag matches or whether the object was modified before or after a specified date, use the request headers x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, or x-amz-copy-source-if-modified-since.

Syntax Example

For a syntax example, see PUT Object - Copy.

Versioning

By default, x-amz-copy-source identifies the current version of an object to copy. However, if the current version is a delete marker, S3 behaves as if the object were deleted.

To copy a different version, use the versionId subresource. If you enable versioning on the target bucket, S3 generates a unique version ID for the object being copied. This version ID is different from the version ID of the source object. S3 returns the version ID of the copied object in the x-amz-version-id response header in the response. Note that if you do not enable versioning or suspend versioning on the target bucket, the version ID S3 generates a null.

Access Permissions

To grant specific permission on an object using a request header, you can either:

Specify a canned (predefined) ACL using the x-amz-acl request header. For more information, see Controlling Access to Resources Using S3 ACLs.
Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-read-acp, and x-amz-grant-write-acp, x-amz-grant-full-control headers. These headers map to the set of permissions S3 supports in an ACL. For more information, see Controlling Access to Resources Using S3 ACLs.

Note:

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

Request Parameters

This implementation of PUT Object Copy operation does not support the use of request parameters.

Request Headers

The PUT Object Copy operation supports the use of following request headers:

Request headers common to all operations. For more information, see table "Common Supported Request Headers" in Supported Common Request Headers.
Request headers for PUT Object operations, which include x-amz-copy-source, x-amz-metadata-directive, x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, x-amz-copy-source-if-modified-since, x-amz-tagging-directive. For a description of these request headers, see PUT Object - Copy.

Request Elements

The PUT Object Copy operation supports the following requests elements:

CopyObjectResult
ETag
LastModified

For a description of the supported request elements, see PUT Object - Copy.

Response Headers

The PUT Object Copy operation supports the use of the following response headers:

Response headers common to all operations. For more information, see table "Supported Response Headers" in Supported Common Response Headers.
Response headers for PUT Object operation, which include x-amz-version-id and x-amz-copy-source-version-id. For a description of these response headers, see PUT Object - Copy.

Response

This implementation of the PUT Object Copy operation does not return response elements.

Expected HTTP Response Code

200 OK

Error Response Code

The PUT Object Copy API does not return special errors. For general information about S3 errors and a list of error codes, see S3 Client Error Handling Reference.

Example

PUT /my-second-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2018 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
HTTP/1.1 200 OK
x-amz-request-id: tx318BC8BC148832E5
x-amz-copy-source-version-id: 0009
x-amz-version-id: 0099
Date: Wed, 28 Oct 2018 22:32:00 GMT
Connection: close
Server: Apache

<CopyObjectResult>
   <LastModified>2009-10-28T22:32:00</LastModified>
   <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
 </CopyObjectResult>

Where x-amz-version-id returns the version ID of the object in the destination bucket, and x-amz-copy-source-version-id returns the version ID of the source object.