ROC API Reference

ROC is an image storage and delivery REST API designed for developers, agencies, and e-commerce stores. Upload an image once—ROC optimizes it, auto-orients smartphone camera shots, strips private GPS data, and stores a single featherlight master file. You dynamically resize, crop, and convert images right inside the delivery URL with zero pre-generated file clutter.

Single Master WebP

ROC stores only one master file on disk. You save 85%+ storage compared with generating 5 duplicate files.

On-the-Fly URL Resizing

Append ?w=320&h=320&fit=cover to any delivery URL. Sizes are transformed dynamically.

1-Year Edge Caching

Every response returns Cache-Control: immutable with granular ETags for instant 304 revalidation.

Authentication

Authenticate all mutating REST API requests by providing your client API key in the x-api-key HTTP request header. Public image delivery URLs do not require authentication.

Header	Type	Description
`x-api-key`	`string` required	Your secret client API key provided upon plan activation.
`Content-Type`	`string`	`multipart/form-data` for uploads, or `application/json`.

Security Notice: Keep your API key confidential. Never expose your API key in client-side frontends (browser JavaScript, mobile apps). Always execute uploads and deletions from your server-side backend.

Quickstart

Upload a file using your preferred language or shell environment:

# 1. Upload an image
curl -X POST https://roc.phyr.in/api/v1/assets \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./banner.jpg"

# 2. Check storage usage
curl https://roc.phyr.in/api/v1/usage \
  -H "x-api-key: YOUR_API_KEY"

import fs from 'fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./banner.jpg')]), 'banner.jpg');

const res = await fetch('https://roc.phyr.in/api/v1/assets', {
  method: 'POST',
  headers: { 'x-api-key': 'YOUR_API_KEY' },
  body: form,
});

const { data } = await res.json();
console.log('Asset URL:', data.url);
console.log('Dynamic 300px thumbnail:', `${data.url}?w=300&h=300&fit=cover`);

import requests

# Upload image
with open('banner.jpg', 'rb') as f:
    res = requests.post(
        'https://roc.phyr.in/api/v1/assets',
        headers={'x-api-key': 'YOUR_API_KEY'},
        files={'file': f}
    )

data = res.json()['data']
print('Master URL:', data['url'])
print('Thumbnail:', data['url'] + '?w=320&h=320')

<?php
$ch = curl_init('https://roc.phyr.in/api/v1/assets');
$cfile = new CURLFile('banner.jpg', 'image/jpeg', 'banner.jpg');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-key: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => $cfile]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Master URL: " . $response['data']['url'];
?>

POST /api/v1/assets 🔒 Requires API key

Upload Image Asset

Uploads a new image asset. ROC validates the binary signature, fixes camera orientation, strips metadata (including GPS coordinates), converts it to an optimized master WebP, and saves it.

Field	Type	Description
`file`	`binary` required	The image file to upload. Formats: JPEG, PNG, WebP, AVIF. Max size: 1 MB (configurable).

Example Response (201 Created)

{
  "success": true,
  "data": {
    "assetId": "286e4874b89705cb",
    "applicationId": "c19ae85529d82109",
    "url": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb",
    "thumbUrl": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb?w=320&h=320",
    "urls": {
      "auto": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb",
      "webp": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb.webp",
      "jpeg": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb.jpg",
      "png": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb.png"
    },
    "filename": "product-hero.png",
    "size": 289410,
    "width": 1920,
    "height": 1080,
    "format": "webp",
    "createdAt": "2026-11-06T10:15:30.000Z"
  }
}

POST /api/v1/assets/replace 🔒 Requires API key

Atomic Asset Replacement (by URL or Asset ID)

Replaces an existing image asset. You can pass either the full image URL (url) or the assetId. You do not need to store or extract the asset ID separately in your database.

Guaranteed safe & atomic: the existing image is never removed from storage or the database until the replacement image has been successfully validated, optimized, and committed. If an upload fails midway, your live image stays intact.

Field	Type	Description
`url` or `assetId`	`string` required	The existing image URL (e.g. `https://roc.phyr.in/c19ae.../286e48...`) or plain `assetId` to replace.
`file`	`binary` required	The new replacement image file.

cURL Example (Replacing by Image URL)

# Pass the image URL directly from your database
curl -X POST https://roc.phyr.in/api/v1/assets/replace \
  -H "x-api-key: YOUR_API_KEY" \
  -F "url=https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb" \
  -F "file=@./new-avatar.jpg"

DELETE /api/v1/assets 🔒 Requires API key

Delete Image Asset (by URL or Asset ID)

Permanently deletes the asset and its stored files, reclaiming disk quota immediately. You can delete an image by passing its full URL (via query parameter ?url=... or JSON body {"url": "..."}) or by passing the assetId in the URL path.

Parameter	Type	Description
`url`	`string` optional	The full ROC delivery URL of the image to delete (e.g. in query `?url=...` or request body).
`assetId`	`string` optional	The ID of the asset to delete (can be passed as a route path parameter: `/api/v1/assets/:assetId`).

Delete Examples

# 1. Delete by full URL (easiest for clients storing only image URLs)
curl -X DELETE "https://roc.phyr.in/api/v1/assets?url=https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb" \
  -H "x-api-key: YOUR_API_KEY"

# 2. Delete with JSON body
curl -X DELETE https://roc.phyr.in/api/v1/assets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb"}'

# 3. Delete by assetId path parameter
curl -X DELETE https://roc.phyr.in/api/v1/assets/286e4874b89705cb \
  -H "x-api-key: YOUR_API_KEY"

GET /api/v1/usage 🔒 Requires API key

Check Client Storage Usage

Returns current on-disk storage utilization, active subscription plan, and limits for the authenticated client.

Example Response (200 OK)

{
  "success": true,
  "data": {
    "client": {
      "id": "c19ae85529d82109",
      "name": "Shopify Storefront",
      "plan": "AURA",
      "storageLimitMb": 5120,
      "maxAssetSizeMb": 1,
      "planStartedAt": "2026-11-01T00:00:00.000Z",
      "planExpiresAt": "2027-11-01T00:00:00.000Z"
    },
    "usage": {
      "totalAssets": 420,
      "storageUsedBytes": 146800640,
      "storageUsedMb": 140,
      "storageLimitMb": 5120,
      "storagePercent": 2.7,
      "remainingMb": 4980
    }
  }
}

GET /:applicationId/:assetId 🌐 Public CDN (No key required)

Public Image Delivery & Dynamic URL Resizing

Every image is delivered over a public CDN URL. When no query parameters are provided, ROC streams the full-resolution master WebP file with zero overhead. To resize or crop, simply add query parameters to the URL.

Supported Query Parameters

Parameter	Type	Default	Description
`w` or `width`	`integer`	original	Target width in pixels (1 to 3840). Scales proportionally if height is omitted.
`h` or `height`	`integer`	original	Target height in pixels (1 to 3840). Scales proportionally if width is omitted.
`fit`	`string`	`inside`	Resizing strategy when both width and height are provided. Options: `cover`, `contain`, `inside`, `fill`, `outside`.
`q` or `quality`	`integer`	`85`	Compression quality from 1 to 100.
`format`	`string`	`webp`	Output format on-the-fly: `webp`, `jpg`, or `png`. Alternatively, append `.jpg` or `.png` directly to the URL.

Aspect Crops & Fit Modes

Mode	Behavior	Best Used For
`fit=cover`	Crops the image to completely fill the specified dimensions while preserving aspect ratio.	Square user avatars, uniform e-commerce product grids, blog hero cards.
`fit=inside`	Downscales the image to fit entirely within the box without cropping or altering aspect ratio.	Product detail zoom view, general galleries (default).
`fit=contain`	Letterboxes the image within the bounding box with transparent background (or white on JPEG).	Brand logos and partner emblems that must never be cropped.
`fit=fill`	Stretches the image to exact dimensions, ignoring aspect ratio.	Distorted texture patterns.

Delivery URL Patterns

URL Examples

# 1. Clean Master URL (Auto-negotiates modern WebP vs JPEG based on browser)
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb

# 2. Dynamic 320x320 Square Thumbnail
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb?w=320&h=320

# 3. Avatar Crop (120x120 cover crop at 80% quality)
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb?w=120&h=120&fit=cover&q=80

# 4. On-the-fly JPEG for Legacy Email Clients (Outlook)
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb.jpg
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb?format=jpg

# 5. Lossless PNG with Transparency
https://roc.phyr.in/c19ae85529d82109/286e4874b89705cb.png

Edge Caching & Performance

ROC is engineered for maximum delivery velocity:

Immutable Header: Cache-Control: public, max-age=31536000, immutable allows browsers and CDNs to cache images for up to 1 full year.
Parameter-Aware ETags: Each unique permutation of w, h, fit, q, and format receives an isolated ETag. When a browser checks back with If-None-Match, ROC responds with an instant 304 Not Modified body-less response.

Standard Response Format

All API endpoints return JSON with a consistent envelope structure:

Standard Error Response

{
  "success": false,
  "error": {
    "code": "STORAGE_LIMIT_EXCEEDED",
    "message": "Storage quota of 2048 MB exceeded. Currently using 2047 MB. Upgrade your plan or delete unused assets."
  }
}

Status Codes & Error Reference

HTTP Status	Error Code	Description
`400 Bad Request`	`VALIDATION_ERROR`	Missing required parameters (e.g. `file` or `assetId`).
`400 Bad Request`	`UNSUPPORTED_FILE_TYPE`	Uploaded file is not a supported image format (JPEG, PNG, WebP, AVIF).
`401 Unauthorized`	`UNAUTHORIZED`	Missing `x-api-key` request header.
`401 Unauthorized`	`INVALID_API_KEY`	The provided API key does not exist or has been revoked.
`403 Forbidden`	`STORAGE_LIMIT_EXCEEDED`	Client has reached their plan's storage quota on disk.
`403 Forbidden`	`PLAN_EXPIRED`	The client's annual subscription plan has expired.
`404 Not Found`	`NOT_FOUND`	Asset ID does not exist or does not belong to the calling client.
`413 Payload Too Large`	`PAYLOAD_TOO_LARGE`	The uploaded image file exceeds the client limit (default 1 MB).

Storage Plans & Quotas

Unlike traditional services that count number of uploads, ROC quotas are measured by actual bytes on disk across your optimized WebP master files.

Plan	Storage Quota	Price	Max Asset Size	Dynamic Resizing
Spark	2 GB	₹4,999 / year	1 MB	Included
Aura (Popular)	5 GB	₹7,499 / year	1 MB	Included
Crown	10 GB	₹9,999 / year	1 MB	Included

Need custom limits or additional storage? Additional capacity is available at ₹100 per 100 MB.