S3 · Objects
PutObject
/{bucket}/{key}Writes an object.
Writes the request body as the object at the key. A write to a key that exists replaces the object. With versioning on, the earlier version stays. When indexing is enabled for the bucket, Graphon indexes the object for search and query.
- Role
- Editor or higher
- Support
- Supported
- One request can carry at most 200 MiB. Storage checks each checksum header that you send. If-None-Match: * creates only.
- The aws CLI and the SDKs switch to a multipart upload for a larger body by themselves.
- Storage accepts
aws-chunkedbodies, signed or unsigned, with checksum trailers.
Path parameters
Headers
The size of the body in bytes. One request can carry at most 200 MiB.
The media type to store with the object.
Default: "application/octet-stream"
Stored with the object and returned on reads.
Stored with the object and returned on reads.
Stored with the object and returned on reads. For an aws-chunked body, storage removes aws-chunked and keeps the other encodings.
Stored with the object and returned on reads.
User metadata. Storage keeps each x-amz-meta- header with the object. GetObject and HeadObject do not return it.
Recorded with the object and shown in listings. It does not change how storage keeps the bytes.
Default: "STANDARD"
Tags for the object, as a URL query. For example, team=support&tier=gold.
Send * to write only when the key has no object. An object at the key returns 412 PreconditionFailed.
Write only when the current ETag matches. Another ETag, or no object, returns 412 PreconditionFailed.
The base64 MD5 digest of the body. A different digest returns 400 BadDigest.
A base64 checksum of the body: crc32, crc32c, crc64nvme, sha1, or sha256. Storage checks it, stores it, and returns it on reads. A different checksum returns 400 BadDigest.
The checksum to compute: CRC32, CRC32C, CRC64NVME, SHA1, or SHA256. x-amz-checksum-algorithm does the same.
The object size of an aws-chunked body. Required with Content-Encoding: aws-chunked or a STREAMING- payload hash. Without it, storage returns 411 MissingContentLength.
The workspace ID that must own the bucket. Another owner returns 403 AccessDenied.
Request body
The bytes of the object.
Responses
200OK
Storage wrote the object.
Response headers
ETagstringThe entity tag of the object, in double quotes.
x-amz-version-idstringThe version ID of the object. Storage gives every write a version ID.
x-amz-checksum-*stringEach checksum that the write stored, such as x-amz-checksum-sha256.
This response has no body.
Errors
Select an error in the response example to see its XML body. Any request can also get the common errors, such as SignatureDoesNotMatch.
- 412PreconditionFailed
If-Match or If-None-Match did not hold.
What to do: Read the object again to get its current ETag, then decide whether to retry.
- 400BadDigest
A checksum header does not match the body. Storage did not keep the bytes.
What to do: Compute the checksum from the bytes that you send, then send the request again.
- 400XAmzContentSHA256Mismatch
The body does not match the SHA-256 that the request signed.
What to do: Hash the bytes that you send, then sign and send the request again.
- 400IncompleteBody
The body ended before the length that the request declared.
What to do: Send the whole body again.
- 411MissingContentLength
An
aws-chunkedbody came withoutx-amz-decoded-content-length.What to do: Send the object size in
x-amz-decoded-content-length.- 413EntityTooLarge
The body is larger than 200 MiB.
What to do: Use a multipart upload. The aws CLI and the SDKs do this for a large file by themselves.
- 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.
- 404NoSuchBucket
No bucket has this name, or the bucket was deleted.
What to do: Check the bucket name. ListBuckets shows the buckets of the workspace.
- 403AccessDenied
The key does not have the role for this operation, or the bucket is in another workspace.
What to do: Use a key of the workspace that owns the bucket, with the role above.