Operations on objects

Edit online

Upload an object
A PUT given a path to an object uploads the request body as an object. A SHA256 hash of the object is a required header. All objects are limited to 10TB in size. This operation does not make use of operation specific query parameters, or payload elements. If versioning is enabled on the bucket, objects will be versioned up to 1,000 times per object in vault mode only. Container mode does not have a limit on how many versions you can have per object.
Upload an object using HTML forms
A POST adds an object to a specified bucket using HTML forms. POST is an alternate form of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are passed to PUT through HTTP Headers are instead passed as form fields to POST in the multipart/form-data encoded message body. All objects are limited to 10TB in size. This operation does not make use of operation specific query parameters. If versioning is enabled on the bucket, objects will be versioned up to 1,000 times per object in vault mode only. Container mode does not have a limit on how many versions you can have per object.
Upload an object to an IBM Immutable Storage protected bucket
This enhancement of the PUT operation adds three new request headers: two for specifying the retention period in different ways, and one for adding a single legal hold to the new object. New errors are defined for illegal values for the new headers. If an object is under retention, it cannot be overwritten or deleted.
Upload an object to an IBM Immutable Storage protected bucket using HTML webforms
Specify retention periods and add a single legal hold to a protected object using webforms.
Upload an object with tagging
Get the headers of an object
A HEAD given a path to an object retrieves that object’s headers. This operation does not make use of operation specific query parameters (besides versioning) or payload elements.
Get the headers of an object protected by IBM Immutable Objects
A HEAD given a path to a protected object retrieves that object’s headers. This operation does not make use of operation specific query parameters (besides versioning) or payload elements.
Download an object
A GET given a path to an object downloads the object. This operation does not make use of operation specific query parameters (besides versioning) or payload elements.
Download a protected object using Immutable Object Storage
Delete an object
A DELETE given a path to an object deletes an object. This operation does not make use of operation specific query parameters (besides versioning), or payload elements.
Delete a protected object using Immutable Object Storage
This enhancement of the DELETE operation adds a new error status. If an object is protected, it cannot be deleted and a 451 Unavailable for Legal Reasons is returned.
Deleting multiple objects
A POST given a path to an bucket and proper parameters will delete a specified set of objects. An integrity check is required by using either content-md5, a x-amz-checksum- header, or the x-amz-content-sha256 header. This operation does not make use of operation specific query parameters (besides versioning), or payload elements.
Delete the tags on an object
Copy an object
A PUT given a path to a new object creates a new copy of another object specified by the x-amz-copy-source header. Unless otherwise altered the metadata remains the same, although any ACL is reset to private for the account creating the copy. This operation does not make use of operation specific query parameters (besides versioning) or payload elements.
Copy a protected object or copy an object to a protected bucket using Immutable Object Storage
This extension to the PUT Object (Copy) operation allows copying an object into another vault and changing the Protection settings on the copy.
Retrieve an object’s ACL
A GET given a path to an object given the parameter ?acl= retrieves the access control list for the object. This operation does not make use of operation specific headers, additional query parameters (besides versioning) or payload elements.
Create an ACL for an object
A PUT issued to an object with the proper parameters creates an access control list (ACL) for that object. Access control lists allow for granting different sets of permissions to different storage accounts using the account’s ID, or by using a pre-made ACL.
Check an object’s CORS configuration
An OPTIONS given a path to an object along with an origin and request type checks to see if that object is accessible from that origin using that request type. Unlike all other requests, an OPTIONS request does not require the authorization or x-amx-date headers. For protected mirrors, the OPTIONS uses the CORS configuration from the fastest vault of the protected mirror.
Adding or extending Object Lock on an object
Object Lock Retention can be applied to an object after it has been uploaded to the system. If an object was uploaded without any applied retention, it can be added with this request. If an object was uploaded with retention applied already (i.e. has an applied “retain-until-date”) then that date can be extended further in the future.
Adding Object Lock legal hold on an object
The Object Lock Legal Hold can be applied to an object after it has been uploaded to the system. If an object was uploaded without any applied retention or legal hold, the legal hold can be added with this request. If an object was uploaded with legal hold applied already, then that legal hold can be turned ON or OFF with this request.
Add or remove a legal hold to or from an IBM Immutable Object protected object
This implementation of the POST operation uses the legalHold subresource and add and remove query parameters to add or remove a single legal hold from a protected object in a protected vault.
Add tags to an object
Extend the retention period of a protected object using Immutable Object Storage
List the tags on an object
Read Object Lock retention on an object
List legal holds on a protected object using Immutable Object Storage
This implementation of the GET operation uses the legalHold sub-resource to return the list of legal holds on an object and related retention state in an XML response body.
Read Object Lock legal hold status on an object
Uploading objects in multiple parts
When working with larger objects, multipart upload operations are recommended to write objects into IBM COS. An upload of a single object can be performed as a set of parts and these parts can be uploaded independently in any order and in parallel. Upon upload completion, IBM COS then presents all parts as a single object. This provides many benefits: network interruptions do not cause large uploads to fail, uploads can be paused and restarted over time, and objects can be uploaded as they are being created.
Upload a part
A PUT request issued to an object with query parameters partNumber and uploadId will upload one part of an object. The parts may be uploaded serially or in parallel, but must be numbered in order.
Upload a part for Object Lock objects
If object lock headers are specified at the time of the initiate Multipart Upload or there is present a default retention configuration on the bucket, then a Content MD-5 header with appropriate value must be included with each part that is uploaded if the V4 Signature does not include the sha256 of the content.
Upload a part for protection using Immutable Object Storage
This enhancement of the UPLOAD PART requires that a Content MD-5 header is included with each part that is uploaded if the V4 Signature does not include the sha256 of the content. However, the Content MD-5 header is not required for UPLOAD PART-COPY requests. The Content MD-5 header and V4 Signature signing are not required for INITIATE MULTI PART UPLOAD requests.
Complete a multipart upload
A POST request issued to an object with query parameter uploadId and the appropriate XML block in the body will complete a multipart upload.
Complete a multipart upload for protected objects using Immutable Object Storage
This enhancement of the Complete Multipart Upload operation adds three new request headers: two for specifying the retention period in different ways, and one for adding a single legal hold to the new object. This operation returns the same errors as the PUT/POST Object operation.
Abort incomplete multipart uploads
A DELETE request issued to an object with query parameter uploadId will delete all unfinished parts of a multipart upload.
Select content from an object
A SELECT command filters the contents of an object using simple structured query language (SQL) statement. SELECT command to filter object content is only supported on structured objects which are formatted as either JSON, CSV or Apache Parquet. The filtered object content will be streamed as records and the output format supported are JSON or CSV.

Parent topic: API reference