S3 · Objects

CopyObject

PUT/{bucket}/{key}with the x-amz-copy-source header

Copies an object to another key.

Storage copies the bytes on its side, with no download. The source can be in another bucket of the same workspace. The copy keeps the metadata and tags of the source unless you replace them.

View as Markdown

Role: Editor or higher
Support: Partial
Auth: SigV4 with your API key

The source needs the Viewer role and must be in the same workspace. A copy across storage providers returns 501.
The key needs the Viewer role on the source and the Editor role on the target.
Storage does not check the x-amz-copy-source-if-* conditions.

Request

https://wspq7ws2np5l8z4.storage.beta.graphon.sh/support-tickets/b.json

PUT /support-tickets/b.json HTTP/1.1
Host: wspq7ws2np5l8z4.storage.beta.graphon.sh
x-amz-date: 20261007T093000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: AWS4-HMAC-SHA256 Credential=<ACCESS_KEY_ID>/20261007/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=<SIGNATURE>
x-amz-copy-source: support-tickets/a.json

Replace wspq7ws2np5l8z4 with your workspace ID. HTTP shows the signed request on the wire. The aws CLI and the SDKs sign for you. The CLI uses the graphon profile, and the SDK samples read GRAPHON_API_KEY.

Response

200

Storage wrote the copy.

HTTP/1.1 200 OK
Content-Type: application/xml
x-amz-request-id: 4F8A2C7D1E6B4093A5C2D8E1F7B3A960

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LastModified>2026-10-07T09:30:00.000Z</LastModified>
  <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

Path parameters

bucketstringrequired

The bucket name.

keystringrequired

The object key. Keep each / as it is. Percent-encode the other reserved characters.

Headers

x-amz-copy-sourcestringrequired

The source, as {bucket}/{key}, URL-encoded. Add ?versionId= to copy one version.

x-amz-metadata-directivestringoptional

Whether to keep the metadata of the source or to use the headers of this request.

Default: "COPY"

COPY: Keep the metadata of the source.
REPLACE: Use Content-Type, the stored headers, and x-amz-meta-* from this request.

x-amz-tagging-directivestringoptional

Whether to keep the tags of the source.

Default: "COPY"

COPY: Keep the tags of the source.
REPLACE: Use the tags in x-amz-tagging.

Content-Typestringoptional

The media type of the copy. Used with REPLACE.

Cache-Controlstringoptional

Stored with the object and returned on reads. Used with REPLACE.

Content-Dispositionstringoptional

Stored with the object and returned on reads. Used with REPLACE.

Content-Encodingstringoptional

Stored with the object and returned on reads. Used with REPLACE.

Content-Languagestringoptional

Stored with the object and returned on reads. Used with REPLACE.

x-amz-meta-*stringoptional

User metadata. Used with REPLACE.

x-amz-storage-classstringoptional

Recorded with the object and shown in listings. Used with REPLACE.

x-amz-taggingstringoptional

Tags for the object, as a URL query. For example, team=support&tier=gold. Used with a tagging directive of REPLACE.

x-amz-expected-bucket-ownerstringoptional

The workspace ID that must own the bucket. Another owner returns 403 AccessDenied.

Responses

200OK

Storage wrote the copy.

application/xml

CopyObjectResultobjectrequired

The root element.

LastModifiedstring

When the copy was written.

ETagstring

The entity tag of the copy.

Errors

Select an error in the response example to see its XML body. Any request can also get the common errors, such as SignatureDoesNotMatch.

400InvalidRequest

The x-amz-copy-source value is not {bucket}/{key}.

What to do: Send the source as {bucket}/{key}, URL-encoded.

404NoSuchKey

The source has no object at this key or version.

What to do: Check the key and the versionId.

404NoSuchBucket

The source bucket or the target bucket does not exist.

What to do: Check the bucket name. ListBuckets shows the buckets of the workspace.

403AccessDenied

The key cannot read the source or write the target, or the source is in another workspace.

What to do: Use a key of the workspace that owns the bucket, with the role above.

501NotImplemented

The source bucket uses another storage provider.

What to do: Copy between buckets of the same provider, or download and upload the object.

405MethodNotAllowed

The versionId names a delete marker, which has no bytes.

What to do: Use the versionId of a version that holds data. ListObjectVersions shows each one.

503SlowDown

The bucket has too many writes in progress. The response has Retry-After: 1.

What to do: Wait for the Retry-After time, then send the request again. SDKs retry by themselves.

Was this page helpful?