Complete REST API Reference

# Standard header:
curl -H "x-api-key: YOUR_API_KEY" http://localhost:7100/v1/...

# Or Bearer header:
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:7100/v1/...

All DevCloudDesk Storage Server endpoints communicate over standard HTTP with JSON payloads and RFC 7578 multipart uploads.

---

Authentication#

Pass your API key in either of the following HTTP headers:

• x-api-key: sk_live_...
• Authorization: Bearer sk_live_...

Root administrative requests also accept x-admin-key: YOUR_MASTER_KEY.

---

1. Ingestion Endpoints#

Upload File (POST /v1/upload)

Uploads a file directly to the storage server using multipart/form-data.

• Headers: x-api-key (required) OR X-Upload-Token (for signed client uploads)
• Content-Type: multipart/form-data
• Form Fields:
  • file (binary, required): The raw file payload.
  • folder (string, optional): Target folder path (e.g. avatars or products/2026).
  • access (string, optional): 'public' (default) or 'private'.

Response (200 OK / 201 Created):

jsonCopy
{
  "success": true,
  "asset": {
    "public_id": "avatars/user-99_a1b2c3d4",
    "publicId": "avatars/user-99_a1b2c3d4",
    "filename": "user-99.jpg",
    "bytes": 184520,
    "mimeType": "image/jpeg",
    "format": "jpg",
    "width": 1200,
    "height": 800,
    "access": "public",
    "url": "http://localhost:7100/image/upload/avatars/user-99_a1b2c3d4.jpg",
    "secure_url": "http://localhost:7100/image/upload/avatars/user-99_a1b2c3d4.jpg",
    "storageDriver": "local",
    "created_at": "2026-10-27T08:30:00.000Z"
  }
}

---

Generate Signed Upload Token (POST /v1/upload/sign)

Generates a short-lived cryptographic token for client-side uploads.

• Headers: x-api-key (required, write role)
• JSON Body:
  • folder (string, optional): Restrict uploads to this folder.
  • maxBytes (number, optional): Maximum allowed file size in bytes.
  • expiresInSeconds (number, optional, default 300): Token TTL in seconds.
  • access (string, optional): 'public' or 'private'.

Response (200 OK):

jsonCopy
{
  "success": true,
  "token": "dcd_sig_eyJpZCI6ImsxMjMiLCJleHAiOjE3NjE1Nzg0MDB9...",
  "uploadUrl": "http://localhost:7100/v1/upload",
  "expiresInSeconds": 300,
  "folder": "avatars",
  "maxBytes": 5242880,
  "access": "public"
}

---

Generate Signed Download URL (POST /v1/download/sign)

Generates an expiring HMAC signed URL to access private assets.

• Headers: x-api-key (required, read role)
• JSON Body:
  • publicId (string, required): Asset public ID.
  • expiresInSeconds (number, optional, default 300): URL TTL in seconds.
  • resourceType (string, optional): 'image' or 'raw'.
  • transform (string, optional): Transformation parameters (e.g. w_400,h_400,c_fill).

Response (200 OK):

jsonCopy
{
  "success": true,
  "publicId": "invoices/inv_2026_001.pdf",
  "signedUrl": "http://localhost:7100/cdn/invoices/inv_2026_001.pdf?exp=1761578400&sig=a8f9c1...&keyId=k123",
  "expiresInSeconds": 300,
  "expiresAt": 1761578400
}

---

2. Delivery & Transformation Endpoints#

Image Transformation (GET /image/upload/* or GET /cdn/*)

Delivers and transforms an image on the fly with smart caching.

• URL Patterns:
  • Path tokens (Cloudinary format): GET /image/upload/{params}/{publicId}
  • CDN route: GET /cdn/{publicId}?w=800&h=600&fit=cover&f=webp&q=80
  • Legacy format: GET /v1/image/{params}/{publicId}
• Query Parameters:
  • w, width: Target width in pixels.
  • h, height: Target height in pixels.
  • fit, crop: 'cover', 'contain', 'fill', 'inside', 'outside'.
  • f, format: 'webp', 'avif', 'jpeg', 'png', 'auto'.
  • q, quality: Compression quality (1 to 100).
  • blur: Gaussian blur radius (1 to 100).
• Headers Returned:
  • ETag: Content hash.
  • Cache-Control: public, max-age=31536000, immutable.
  • Vary: Accept (when f=auto is requested).

---

Raw Asset Delivery (GET /raw/upload/* or GET /cdn/*)

Delivers non-image assets (PDFs, videos, audio, archives) without transformation.

• Query Parameters:
  • download=1: Sets Content-Disposition: attachment; filename="..." to force browser file download.

---

3. Administration Endpoints#

Server Statistics (GET /v1/admin/stats)

Returns real-time cluster metrics, memory, file counts, and cache statistics.

• Headers: x-api-key or x-admin-key (required)

Response (200 OK):

jsonCopy
{
  "success": true,
  "stats": {
    "filesCount": 1420,
    "totalStorageBytes": 542198000,
    "cacheVariantsCount": 3810,
    "cacheSizeBytes": 89201500,
    "uptimeSeconds": 86420,
    "memoryUsageMb": 64,
    "storageDriver": "local"
  }
}

---

List Media Files (GET /v1/admin/files)

Returns paginated assets with metadata and direct URLs.

• Query Parameters:
  • page (number, default 1): Current page.
  • limit (number, default 50, max 100): Items per page.
  • folder (string, optional): Filter by folder prefix.

Response (200 OK):

jsonCopy
{
  "success": true,
  "data": {
    "files": [
      {
        "publicId": "avatars/user-99.jpg",
        "filename": "user-99.jpg",
        "bytes": 184520,
        "format": "jpg",
        "width": 1200,
        "height": 800,
        "access": "public",
        "url": "http://localhost:7100/image/upload/avatars/user-99.jpg",
        "secure_url": "http://localhost:7100/image/upload/avatars/user-99.jpg",
        "createdAt": "2026-10-21T14:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1420,
      "totalPages": 29,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

---

Update Asset Access (PATCH /v1/admin/files/*)

Updates the access permission mode of an existing asset without re-uploading.

• Headers: x-api-key (write/admin role) or x-admin-key
• JSON Body:
  • access: 'public' or 'private'

Response (200 OK):

jsonCopy
{
  "success": true,
  "publicId": "avatars/user-99.jpg",
  "access": "private"
}

---

Delete Asset (DELETE /v1/admin/files/*)

Permanently deletes an asset from storage and purges all cached transformation variants.

• Headers: x-api-key (delete role) or x-admin-key

Response (200 OK):

jsonCopy
{
  "success": true,
  "deleted": true,
  "message": "File 'avatars/user-99.jpg' deleted successfully"
}

---

Purge Transformation Cache (POST /v1/admin/purge-cache)

Invalidates and purges all on-the-fly generated image transformation variations from server disk cache.

• Headers: x-api-key (delete/admin role) or x-admin-key

Response (200 OK):

jsonCopy
{
  "success": true,
  "purgedCount": 3810,
  "purgedBytes": 89201500
}

---

Create API Key (POST /v1/admin/keys)

Creates a new granular API key for an application or microservice.

• JSON Body:
  • name (string, required): Descriptive label for the key.
  • type (string, optional): 'secret' (full permissions) or 'public'.
  • permissions (array of strings, optional): ['read', 'write', 'delete', 'admin'].
  • rateLimit (number, optional, default 120): Allowed requests per minute.

Response (201 Created):

jsonCopy
{
  "success": true,
  "key": "sk_live_99a8b1c4e23740291fa8b4c2",
  "apiKey": {
    "id": "k_189283",
    "name": "Production Backend",
    "permissions": ["read", "write", "delete", "admin"],
    "rateLimit": 120,
    "createdAt": 1761578400
  }
}

---

Next Steps#

• CLI Tool & Key Management →: Manage the server directly from your terminal.
• Client SDK Installation →: Use the official SDK instead of raw HTTP calls.