Rename Objects

Rename objects in Object Storage

The S3-compatible RenameObject API provides an atomic, server-side rename operation for a single object within the same bucket, with no data movement and metadata preserved.

This operation is simpler and more efficient to use than a copy and delete operation. Rename operations typically complete in milliseconds regardless of object size, because the operation updates index entries instead of copying object data. Since no data is copied, you do not incur temporary double storage usage during rename operations.

You can use standard S3-compatible tools and SDKs, including the AWS CLI and Boto3, to interact with the RenameObject API.

Prerequisites

Before using RenameObject, make sure you have:

• An active CoreWeave account.
• A valid API Access Key and Secret Token.
• s3:PutObject on the destination and s3:DeleteObject on the source. See Ensure permissions for details.
• A unversioned bucket. A bucket is unversioned if it has never had versioning enabled. "Versioning suspended" is not supported.
• Endpoint configured for virtual-hosted addressing.

How it works

Atomicity

RenameObject is atomic and performs a metadata-only remap of the object key. There is no data copy and no temporary duplication of object data. With copy and delete, there is a window where both keys may exist and large objects incur additional latency for the copy step.

RenameObject eliminates that window and avoids the extra data movement overhead.

Metadata preservation

RenameObject preserves object metadata, including encryption settings, storage billing tier, checksums, and related attributes supported by AI Object Storage.

Consistency

AI Object Storage maintains read-after-write consistency for RenameObject: After a successful response, reads to the destination key see the object. Reads that are concurrent with a successful rename will see exactly one of the source or the destination (assuming no other writes).

LOTA support

When LOTA is in use, rename updates the metadata/index mapping so that cached content (if present) is immediately associated with the new key. This preserves LOTA's performance benefits without requiring data to be re-cached.

Limitations

Currently, the RenameObject API only supports renaming a single object within the same bucket. If you need to rename objects across buckets, continue to use copy+delete semantics.

Limitation	Description
Same bucket only	The source and destination keys must be in the same bucket.
Versioning not supported	Rename is not supported for buckets where versioning is enabled or has ever been enabled. Specifically, "unversioned" buckets are supported while "versioning enabled" and "versioning suspended" are not supported. If versioning is currently enabled, or was previously enabled on the bucket, the RenameObject request fails with an error and the object is not renamed.
Single object only	Each request renames one object key. Prefix-scale rename operations are not yet supported, so this must be implemented as client-side batches that call RenameObject once per object.
Rate limits and high-QPS workloads	Very high-QPS prefix-scale workflows may be subject to rate shaping or recommended batching guidance to avoid operational impact. Consult your CoreWeave contact if you plan large rename campaigns at scale.

Preconditions and safeguards

RenameObject supports conditional headers to help you guard against accidental overwrites and race conditions. Typical preconditions include ETag-based and time-based conditions.

Preconditions ensure the rename only proceeds when the source/destination state matches your expectations. An idempotency token lets you safely retry the same operation without creating multiple conflicting renames.

Example ETag-based conditions:

Source conditions:

• Rename only if the source ETag matches the value you provide (If-Match).
• Rename only if the source ETag does not match a value you provide (If-None-Match).

Destination conditions:

• Rename only if the destination does not already exist.
• Rename only if the destination ETag matches or does not match a specific value.

Example time-based conditions:

• Rename only if the source has been modified since a specified time.
• Rename only if the source has not been modified since a specified time.

If any precondition fails, RenameObject returns a precondition failed error and does not rename the object.

Rename an object

This section walks through the typical steps to use RenameObject safely with CoreWeave AI Object Storage.

Here's the HTTP request syntax for the RenameObject API. Replace the placeholders with the appropriate values for your request, and make sure to use the correct endpoint URL for your CoreWeave AI Object Storage bucket.

Example

PUT /{Key+}?renameObject HTTP/1.1
Host: {bucket-name}.cwobject.com
x-amz-rename-source: /{RenameSource}
If-Match: {DestinationIfMatch}
If-None-Match: {DestinationIfNoneMatch}
If-Modified-Since: {DestinationIfModifiedSince}
If-Unmodified-Since: {DestinationIfUnmodifiedSince}
x-amz-rename-source-if-match: {SourceIfMatch}
x-amz-rename-source-if-none-match: {SourceIfNoneMatch}
x-amz-rename-source-if-modified-since: {SourceIfModifiedSince}
x-amz-rename-source-if-unmodified-since: {SourceIfUnmodifiedSince}
x-amz-client-token: {ClientSuppliedIdempotencyToken}

For API details, refer to AI Object Storage S3 compatibility.

Confirm bucket eligibility

Make sure the bucket meets the following requirements:

• The bucket is a CoreWeave AI Object Storage bucket.
• Versioning has never been enabled on the bucket.
• Both the source and destination keys are in the same bucket.

Ensure permissions

The principal calling RenameObject must be allowed to perform delete (s3:DeleteObject) on the source and put (s3:PutObject) on the destination for the relevant bucket and relevant key prefixes, according to your AI Object Storage organization access policies and bucket policies.

In many environments, this will be combined with broader AI Object Storage permissions such as read and delete access to the source key and write/overwrite permissions on the destination key, as expressed in your policies.

Example policy

The following example shows a pattern for allowing rename operations within a single bucket:

Example bucket policy allowing rename operations within a single bucket

{
  "policy": {
    "version": "v1alpha1",
    "name": "allow-rename-object-within-bucket",
    "Statement": [
      {
        "name": "AllowRenameObjectWithinBucket",
        "effect": "Allow",
        "principals": ["*"],
        "actions": ["s3:PutObject", "s3:DeleteObject"],
        "resources": ["my-bucket/*"],
        "conditions": {
          "StringEquals": {
            "cw:PrincipalOrgID": ["Org ID"]
          }
        }
      }
    ]
  }
}

Important

If you specify the wildcard principal (*) in a bucket policy, always use the conditions field to scope the policy to your organization.

If there are different permissions for the source and destination, you can use multiple statements in the bucket policy to allow the different permissions. Make sure that s3:DeleteObject is granted on the source and s3:PutObject is granted on the destination for the relevant bucket and relevant key prefixes, according to your AI Object Storage organization access policies and bucket policies.

See examples of organization policies and bucket policies for more information.

Run the rename operation

Use the AWS CLI or Boto3 to rename an object. Add optional precondition parameters (ETag or time-based conditions) and an idempotency token as needed.

AWS CLI

Example

$
aws s3api rename-object \
  --bucket my-bucket-name \
  --key my-destination-file.txt \
  --rename-source /my-bucket-name/my-source-file.txt

Boto3

Example

import boto3

s3 = boto3.client('s3')

response = s3.rename_object(
    Bucket='my-bucket-name',
    Key='my-destination-file.txt',
    RenameSource='/my-bucket-name/my-source-file.txt'
)

print(f"Object renamed. ETag: {response['ETag']}")

HTTP

Example

PUT /my-destination-file.txt?renameObject HTTP/1.1
Host: my-bucket-name.cwobject.com
x-amz-rename-source: /my-source-file.txt
If-Match: 1b2cf535f27731c97434645a985325

s3cmd

The s3cmd mv command performs a copy-and-delete operation, not an atomic rename. Use the AWS CLI or Boto3 for atomic RenameObject operations.

Response

A successful rename returns HTTP 200 with the object's ETag:

Example

HTTP/1.1 200 OK
ETag: "1b2cf535f27731c97434645a985325"

Common errors

Error	Cause
PreconditionFailed	ETag or time-based condition not met
NoSuchKey	Source object does not exist
InvalidBucketState	Bucket has versioning enabled or was previously enabled
InvalidRequest	Source and destination are in different buckets

Verify the rename

After a successful response:

• A GET to the new key returns the object.
• A GET to the old key returns a not-found error (for buckets where rename is supported).

If you are using LOTA:

• Use the LOTA endpoint (http://cwlota.com) for the rename request.
• The rename operation updates the metadata/index mapping so that cached content is immediately accessible via the new key.
• Cache entries under the old key are invalidated or remapped so that subsequent reads do not serve stale data from the old name.

Example workflows

These examples illustrate how RenameObject fits typical AI Object Storage workflows.

Promote a temporary checkpoint to a final name

Pattern: foo.ckpt.tmp → foo.ckpt at the end of a training run.

Your training job writes checkpoints to a temporary key, such as checkpoints/run-123/epoch-10.ckpt.tmp. After verifying the checkpoint, call RenameObject to move it to checkpoints/run-123/epoch-10.ckpt. Downstream jobs and inference pipelines read from the stable, final key without any copy cost or latency.

Finalize media or batch outputs

Pattern: Rename final artifacts out of staging prefixes for media processing or ETL.

Write intermediate artifacts under a staging prefix, such as media/staging/job-42/output.mp4. When validation succeeds, rename to media/final/output-2025-12-01.mp4. Monitoring, distribution, or analytics systems are configured to watch the final prefix only.

Rotate logs or time-based data

Pattern: "Lock" an hourly or daily prefix by renaming to a final form.

Write logs under logs/ingest/2025/12/12/10/. When the ingest window closes, rename the prefix contents one object at a time into a finalized prefix such as logs/final/2025/12/12/10/. Consumers rely on the final prefix, with RenameObject ensuring each file appears atomically under its new name.

Currently, the RenameObject API does not support renaming an entire prefix at once. Use batch clients or pipeline logic to apply RenameObject per object for prefix-scale workflows.

Support

If you need help with Rename Object, contact CoreWeave support.

When opening a case, please include the following information:

• The bucket name.
• The source and destination keys.
• Approximate timestamp of the request.
• Any relevant request IDs or error messages from your client or logs.