Media API

Upload and manage images for products, categories, and pages. Files are stored on Cloudflare R2 and served via global CDN for fast delivery.

Key Features

Multipart Upload — Upload multiple images in a single request
Global CDN — Cloudflare R2 with edge caching worldwide
Image Types — JPEG, PNG, WebP, GIF supported

Endpoints

Method	Endpoint	Description
GET	/media	List all media
POST	/media	Upload images (multipart/form-data)
GET	/media/:id	Get media details
PUT	/media/:id	Update alt text
DELETE	/media/:id	Delete media

All endpoints are prefixed with /stores/{storeId}.

The Media Object

{
  "id": "media_abc123",
  "storeId": "store_xyz789",
  "url": "https://cdn.barecommercecore.com/store_xyz789/a1b2c3d4.jpg",
  "mimeType": "image/jpeg",
  "width": 1200,
  "height": 800,
  "fileSize": 245678,
  "altText": "Product lifestyle shot - blue t-shirt",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Fields

Field	Type	Description
id	string	Unique identifier (UUID)
url	string	Public CDN URL for the image
mimeType	string	MIME type (e.g., "image/jpeg")
width	number?	Image width in pixels
height	number?	Image height in pixels
fileSize	number	File size in bytes
altText	string?	Alt text for accessibility/SEO

Upload Images

POST /stores/{storeId}/media
Content-Type: multipart/form-data

Supported Formats

image/jpeg — JPEG images
image/png — PNG images
image/webp — WebP images
image/gif — GIF images

Example: Upload Single Image

curl -X POST "https://api.barecommercecore.com/stores/{storeId}/media" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "files=@product-photo.jpg"

Example: Upload Multiple Images

curl -X POST "https://api.barecommercecore.com/stores/{storeId}/media" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "files=@product-front.jpg" \
  -F "files=@product-back.jpg" \
  -F "files=@product-detail.jpg"

Response

{
  "items": [
    {
      "id": "media_abc123",
      "url": "https://cdn.barecommercecore.com/store_xyz/a1b2c3d4.jpg",
      "mimeType": "image/jpeg",
      "fileSize": 245678,
      "altText": null,
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}

ℹ️ Unique Filenames: Uploaded files are assigned unique names (UUID-based) to prevent conflicts.

List Media

GET /stores/{storeId}/media

Query Parameters

Parameter	Type	Description
limit	integer	Results per page (1-200, default: 50)
offset	integer	Number of items to skip
mimeType	string	Filter by MIME type prefix (e.g., "image/jpeg")

Update Media

Update the alt text for an image. The image file itself cannot be replaced.

curl -X PUT "https://api.barecommercecore.com/stores/{storeId}/media/media_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "altText": "Blue cotton t-shirt front view" }'

Delete Media

Permanently delete an image from storage.

curl -X DELETE "https://api.barecommercecore.com/stores/{storeId}/media/media_abc123" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
 
# Returns 204 No Content

⚠️ Permanent Deletion: Deleted images cannot be recovered. Products referencing deleted media will have broken image links.

Using Media with Products

// 1. Upload images
const formData = new FormData();
formData.append('files', mainImage);
formData.append('files', galleryImage1);
 
const { items: uploadedMedia } = await uploadMedia(formData);
 
// 2. Create product with media references
const product = await createProduct({
  title: 'Blue T-Shirt',
  slug: 'blue-t-shirt',
  price: '29.99',
  primaryMediaId: uploadedMedia[0].id,      // Main product image
  mediaIds: uploadedMedia.map(m => m.id),   // All gallery images
});

CDN URLs

All uploaded images are served via Cloudflare's global CDN:

https://cdn.barecommercecore.com/{storeId}/{uniqueId}.{extension}

Images are cached at edge locations worldwide with Cache-Control: public, max-age=31536000.

Error Responses

400 No Files Provided

{
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [{ "field": "files", "reason": "No files provided" }]
  }
}

400 Invalid File Type

{
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [{ "field": "files", "reason": "Invalid file type: application/pdf" }]
  }
}

Best Practices

Optimize images before upload — Compress to reduce file size
Use WebP format when possible — Better compression than JPEG/PNG
Set descriptive alt text — Improves accessibility and SEO
Clean up unused media — Delete orphaned images periodically

Related Guides

Products — Add images to products
Categories — Set category SEO images

Inventory Webhooks