PUT /v1/buckets/{bucket_name}/objects/{object_key}

Create or Replace Object

Uploads a new object to the specified bucket, or replaces an existing object with the same key. The endpoint supports single-part uploads up to 5GB. For larger files, use the Multipart Upload API.

Authentication: Requires a valid API key passed in the Authorization: Bearer <token> header. The key must have object.write scope.

Request Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token with `object.write` permissions.
Content-TypeRequired	string	MIME type of the object (e.g., `image/png`, `application/json`).
X-CNX-Storage-ClassOptional	enum	Storage tier: `STANDARD`, `COLD`, or `ARCHIVE`. Defaults to `STANDARD`.
X-CNX-Cache-ControlOptional	string	CSS/CDN caching directives (e.g., `max-age=31536000`).

Path Parameters

Parameter	Type	Description
bucket_nameRequired	string	Name of the target bucket. Must be globally unique within your project.
object_keyRequired	string	The full path/key of the object (e.g., `images/2024/banner.png`).

Request Body

The raw binary payload of the object to be uploaded. Maximum size: 5,242,880 bytes (5 GB). For payloads exceeding this limit, use the POST /multipart/upload endpoint.

Response Codes

200 OK Object successfully created or replaced.
400 Bad Request Invalid bucket name, missing headers, or payload exceeds limit.
401 Unauthorized Invalid or expired API token.
429 Too Many Requests Rate limit exceeded (1000 req/min per API key).

Success Response (200)

JSON 200 OK

{
  "object_id": "obj_8f7d6e5c4b3a2910",
  "bucket": "cdn-assets-prod",
  "key": "images/2024/banner.png",
  "size_bytes": 2458624,
  "content_type": "image/png",
  "storage_class": "STANDARD",
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "url": "https://cdn.cloudnexus.io/cdn-assets-prod/images/2024/banner.png",
  "created_at": "2025-01-15T14:32:00Z"
}

Code Examples

cURL Python JavaScript

# Upload a file using cURL
curl -X PUT "https://api.cloudnexus.io/v1/buckets/my-bucket/objects/data.csv" \\
  -H "Authorization: Bearer $CNX_API_KEY" \\
  -H "Content-Type: text/csv" \\
  -H "X-CNX-Storage-Class: COLD" \\
  --data-binary @./path/to/data.csv

# Upload using Python requests
import requests

url = "https://api.cloudnexus.io/v1/buckets/my-bucket/objects/data.csv"
headers = {
    "Authorization": f"Bearer {os.environ['CNX_API_KEY']}",
    "Content-Type": "text/csv",
    "X-CNX-Storage-Class": "COLD"
}

with open("./data.csv", "rb") as f:
    response = requests.put(url, headers=headers, data=f)
    print(response.json())

// Upload using Node.js fetch
const fs = require('fs');

async function uploadObject() {
  const buffer = fs.readFileSync('./data.csv');
  const res = await fetch('https://api.cloudnexus.io/v1/buckets/my-bucket/objects/data.csv', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.CNX_API_KEY}`,
      'Content-Type': 'text/csv'
    },
    body: buffer
  });
  return res.json();
}

Rate Limits & Best Practices

Maximum upload size via this endpoint: 5 GB. Use Multipart Upload for larger files.
Default rate limit: 1,000 requests/minute per API key. Contact sales for higher throughput.
Always include Content-Type to enable proper CDN caching and browser handling.
Use idempotent keys when retrying failed uploads to prevent duplicate objects.