Shard Cloud CDN - Shard Cloud

Overview

Shard Cloud CDN is a fully managed file delivery network — think S3 + CloudFront in one step. Upload your images, videos, documents, or any supported file, and we automatically serve them through a global edge network with caching, compression, and expiration handling built in. The goal is simple: upload a file and get a URL. No infrastructure to configure, no cache rules to write, no CDN invalidation to think about. Every plan includes a free CDN storage quota. You can check the CDN quota included in each plan on the pricing page.

Built-in Features

Edge Caching

Files are cached at edge locations worldwide. Your users get the fastest possible response times regardless of where they are.

Image Compression

Images are automatically compressed and optimized on delivery without quality loss. No extra configuration needed.

Expiration Handling

Set an optional expire_at timestamp on any file. Expired files are automatically cleaned up — great for temporary assets, signed URLs, or time-limited content.

Folder Organization

Organize files into folders using the optional folder parameter. Purge an entire folder’s cache, or delete a whole folder, in a single API call.

File Size Limits

Constraint	Value
Minimum file size	2 KB
Maximum file size, single request (`POST /cdn/files`)	100 MB
Maximum file size, large file upload	10 GB (and never more than your remaining CDN quota)

File Names

Constraint	Value
Allowed characters	Letters (`a-z`, `A-Z`), numbers, underscores (`_`), and hyphens (`-`)
Length	1–64 characters (same rules for `folder`)
Extension	Do not include one — it is added automatically from the file’s MIME type (e.g. `photo` + `image/png` → `photo.png`)

The folder name error-pages is reserved.

Supported File Types

The CDN validates files by their MIME type and magic bytes. We support images, videos, audio, documents (PDF), archives, fonts, and text formats (JSON, CSV, CSS, plain text). For the full list of accepted MIME types, see the Supported File Types page.

Quick Start

Upload a file:

curl -X POST https://shardcloud.app/api/cdn/files \
  -H "Authorization: Bearer {api_token}" \
  -F "file=@photo.png" \
  -F "filename=photo" \
  -F "folder=avatars"

The response includes a url field — that’s your globally cached CDN link, ready to use. List your files:

curl https://shardcloud.app/api/cdn/files \
  -H "Authorization: Bearer {api_token}"

List the files of one folder:

curl "https://shardcloud.app/api/cdn/files?folder=avatars" \
  -H "Authorization: Bearer {api_token}"

Results come 100 per page; pass the returned cursor back as ?cursor= to get the next page. folder can be combined with search to filter by name inside the folder. Delete several files at once (up to 30 per request):

curl -X POST https://shardcloud.app/api/cdn/files/delete \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{"filenames": ["avatars/logo.png", "notes.txt"]}'

The response lists what was deleted and what failed, per file — a missing file doesn’t stop the others:

{ "deleted": ["avatars/logo.png"], "failed": [{ "filename": "notes.txt", "error": "file not found" }] }

Check your usage:

curl https://shardcloud.app/api/cdn/stats \
  -H "Authorization: Bearer {api_token}"

Large File Uploads

A single POST /cdn/files request is limited to 100 MB. For bigger files (up to 10 GB), upload in parts with two extra endpoints:

POST /cdn/files/multipart — starts the upload and returns one upload URL per part.
POST /cdn/files/multipart/{upload_id}/finalize — assembles the parts once they are all sent.

Between the two calls you PUT each part’s bytes to its URL. Those URLs need no Authorization header — each one is a private credential, so don’t share them.

How it works

1. Start the upload with the exact size of the file in bytes:

curl -X POST https://shardcloud.app/api/cdn/files/multipart \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{"filename": "backup", "folder": "videos", "mime_type": "video/mp4", "size": 1073741824}'

{
  "id": "0192b7a4-3c1e-7f2a-9d55-6a1f0c2e8b10",
  "filename": "videos/backup.mp4",
  "parts": [
    { "part_number": 1, "url": "https://shardcloud.app/api/cdn/upload/...", "size": 67108864 },
    { "part_number": 2, "url": "https://shardcloud.app/api/cdn/upload/...", "size": 67108864 }
  ],
  "expires_at": "2026-09-26T07:45:00Z"
}

The file name and the storage quota are reserved at this point, so a file that doesn’t fit your quota is refused immediately. 2. Upload every part. Every part is exactly 64 MiB (67,108,864 bytes) except the last, which holds the remainder — each part’s size tells you how many bytes to send. PUT the bytes of part n (bytes (n-1) × 64 MiB onward) to that part’s url:

# split -b 67108864 backup.mp4 part_   →   part_aa, part_ab, ...
curl -X PUT "{part_1_url}" --data-binary @part_aa
curl -X PUT "{part_2_url}" --data-binary @part_ab

The Content-Length must match the part’s size exactly, otherwise the request is rejected with 403. Parts can be sent in any order, in parallel, and a failed part can simply be sent again. A successful upload answers 200. 3. Finalize:

curl -X POST https://shardcloud.app/api/cdn/files/multipart/{id}/finalize \
  -H "Authorization: Bearer {api_token}"

It returns the file with its CDN url, exactly like a normal upload. Calling finalize again after it succeeded returns the same file, so it is safe to retry if a response gets lost.

Good to know

Time limit: the part URLs and finalize work for 3 hours 50 minutes after you start. After that the reservation is released and you need to start again. If you set expire_at, it must be later than that window.
Not public until finalized: the file shows up in GET /cdn/files with "status": "pending" and has no url until finalize succeeds.
Validation: finalize checks that every part was uploaded with the right size, that the total matches the size you declared, and that the file’s content matches its MIME type. If the content check fails, the upload is discarded and the quota is released.
Cancelling: DELETE /cdn/files?fileName={filename} on a pending upload discards the uploaded parts and releases the reserved quota.
Same rules as normal uploads: valid subscription, supported file types, file name rules, and the file count limit all apply.

CDN API Reference

For the full list of endpoints, request/response schemas, and parameters, see the CDN API Reference section in the sidebar.

​Overview

​Built-in Features

Edge Caching

Image Compression

Expiration Handling

Folder Organization

​File Size Limits

​File Names

​Supported File Types

​Quick Start

​Large File Uploads

​How it works

​Good to know

​CDN API Reference