Skip to main content

Files Handling API (NEW)

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-06-21 Version: v1.0

Base URL: https://your-api-domain.com/api/v1

Short Description: This document covers everything a frontend developer needs to handle files on the NexGate/Veepii platform — uploading, tracking processing progress, reading variant URLs from entity responses, and downloading private files. Files are managed by an internal service called FileThunder; the frontend never talks to FileThunder directly. All file-related operations go through the main backend endpoints documented here.

Hints:

  • All upload endpoints require a valid Bearer token
  • Files are never uploaded through the backend server — you upload directly to object storage using a time-limited presigned URL returned by the backend
  • The backend stores only object key paths; full CDN/MinIO URLs are assembled at response time — always use the URLs in entity responses as-is
  • Processing is asynchronous — after uploading, you track progress via SSE or polling, then the entity response will include the resolved variant map once processing is complete
  • Private files (digital products, DM documents) are never served via CDN — always request a fresh download URL before initiating a download

How File Handling Works — Big Picture

Understanding this flow will save you from confusion. There are two separate progress concepts:

  1. Upload progress — bytes travelling from the client to object storage. You can show a progress bar for this using XMLHttpRequest.
  2. Processing progress — FileThunder processing those bytes into variants (WebP images, transcoded video resolutions, virus scans). You track this via SSE or polling.
┌─────────┐     Step 1: Request presigned URL      ┌──────────────┐
│  Client │ ──────────────────────────────────────► │ Main Backend │
│         │ ◄────────────────────────────────────── │              │
│         │     { fileId, presignedUrl, expiresIn } └──────────────┘
│         │
│         │     Step 2: PUT file bytes directly         ┌─────────┐
│         │ ────────────────────────────────────────►   │  MinIO  │
│         │ ◄────────────────────────────────────────   │         │
│         │     HTTP 200 (upload complete)              └────┬────┘
│         │                                                  │ MinIO fires event
│         │     Step 3: Open SSE stream                      ▼
│         │ ──────────────────────────────────────► ┌──────────────┐
│         │ ◄── status events (PROCESSING, READY) ── │ Main Backend │
└─────────┘                                          └──────────────┘
                                                          │ on READY
                                                          ▼
                                                  Variants saved to entity in DB
                                                  Entity response includes variant URLs

Standard Response Format

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {}
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field Type Description
success boolean true for success, false for errors
httpStatus string HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message string Human-readable result description
action_time string ISO 8601 timestamp of the response
data object/string Response payload or error details

HTTP Method Badge Standards

  • GET — GET
  • POST — POST
  • PUT — PUT

File Contexts

Every upload must declare a context. Context tells FileThunder what this file is for, which determines how it is processed, what variants are generated, and how it is stored.

Context Domain What it is Who uploads it
SOCIAL_IMAGE Posts Image attached to a post or story Authenticated user
SOCIAL_VIDEO Posts Video attached to a post or story Authenticated user
PROFILE_PICTURE Profiles User avatar / profile photo Authenticated user
COVER_PHOTO Profiles Profile cover / banner image Authenticated user
DM_IMAGE Messages Image sent in a direct message Authenticated user
DM_VIDEO Messages Video sent in a direct message Authenticated user
DM_DOCUMENT Messages Document sent in a direct message Authenticated user
PRODUCT_IMAGE Products Product listing photo Shop owner
PRODUCT_VIDEO Products Product demo/preview video Shop owner
DIGITAL_PRODUCT Products Purchasable digital file (PDF, ZIP, software, etc.) Shop owner
SHOP_BANNER Shops Shop header banner image Shop owner
SHOP_LOGO Shops Shop logo / avatar Shop owner
EVENT_COVER Events Event banner/hero image Event organiser
EVENT_GALLERY Events Additional event gallery image Event organiser

File Format & Size Constraints

These are the accepted formats and recommended limits per context. FileThunder enforces the actual limits server-side — passing incorrect mimeType or oversized files will result in a rejection at the presigned URL stage.

Images

Context Accepted MIME Types Max Size Min Dimensions Recommended Dimensions
SOCIAL_IMAGE image/jpeg, image/png, image/webp, image/gif 20 MB 200 × 200 px 1080 × 1080 px (square) or 1080 × 1920 px (portrait)
PROFILE_PICTURE image/jpeg, image/png, image/webp 10 MB 100 × 100 px 400 × 400 px square
COVER_PHOTO image/jpeg, image/png, image/webp 15 MB 600 × 200 px 1500 × 500 px
DM_IMAGE image/jpeg, image/png, image/webp, image/gif 20 MB — —
PRODUCT_IMAGE image/jpeg, image/png, image/webp 20 MB 400 × 400 px 1000 × 1000 px square
SHOP_BANNER image/jpeg, image/png, image/webp 15 MB 800 × 200 px 1200 × 400 px
SHOP_LOGO image/jpeg, image/png, image/webp 5 MB 100 × 100 px 400 × 400 px square
EVENT_COVER image/jpeg, image/png, image/webp 15 MB 800 × 400 px 1200 × 630 px
EVENT_GALLERY image/jpeg, image/png, image/webp 20 MB 200 × 200 px 1080 × 1080 px

Videos

Context Accepted MIME Types Max Size Max Duration Notes
SOCIAL_VIDEO video/mp4, video/quicktime, video/webm, video/x-msvideo, video/x-matroska 100 MB 60 min Videos ≥ 3 min get HLS adaptive streaming
DM_VIDEO video/mp4, video/quicktime, video/webm 100 MB 60 min Always sequential MP4 transcoding
PRODUCT_VIDEO video/mp4, video/quicktime, video/webm, video/x-msvideo, video/x-matroska 100 MB 60 min Videos ≥ 3 min get HLS adaptive streaming

Other

Context Accepted MIME Types Max Size Notes
DM_DOCUMENT application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/zip, text/plain 50 MB ClamAV scanned; no variants generated
DIGITAL_PRODUCT Any — PDF, ZIP, EXE, APK, MP3, etc. 5 GB ClamAV dual-scan + SHA-256 deduplication; never CDN served; always presigned download

Processing Status Lifecycle

After the file reaches object storage, FileThunder processes it through these states. You will receive these values from both the SSE stream and the status polling endpoint.

PENDING ──► UPLOADING ──► UPLOADED ──► SCANNING ──► PROCESSING ──► READY
                                                                  └──► FAILED
                                                         │
                                                    LIVE_PARTIAL
                                               (video 360p is done,
                                                 higher resolutions
                                                  still processing)
Status Meaning UI suggestion
PENDING Upload slot created, waiting for file bytes Show spinner
UPLOADING File bytes are being received by storage Show upload progress bar (XHR)
UPLOADED All bytes received, handing off to processing Show spinner
SCANNING ClamAV virus scan in progress (digital products / DM docs only) "Scanning for safety..."
PROCESSING Transcoding / image variant generation in progress "Processing..."
LIVE_PARTIAL Videos only — 360p variant is ready, higher resolutions still processing Show video with 360p, overlay "HD processing" badge
READY All variants generated and available Dismiss progress UI, display media
FAILED Processing failed Show error, offer re-upload option

Variant Keys

When a file reaches READY, its variants are stored in the entity's database record and returned in entity API responses. Here are all possible variant keys and what they contain.

Image Variants

Key Format Typical Use
large WebP URL Full-size display, lightbox, detail view
medium WebP URL Feed cards, grid thumbnails
thumb WebP URL Tiny previews, avatar chips, comment icons
og WebP URL <meta property="og:image"> Open Graph tag
blurhash String (e.g. LGF5?xYk^6...) CSS blur placeholder while image loads
lqip data:image/webp;base64,... inline data URI Inline <img src> placeholder, no extra request
dominant_color Hex string (e.g. #F06023) Background color while loading, skeleton screen tint

Not every key is present for every context. blurhash and lqip are always generated. large, medium, og, and dominant_color depend on the context — see the Context → Variants Cheat Sheet at the bottom of this document for the exact set per context.

Usage priority: Render lqip or apply blurhash immediately. Swap in medium or large once loaded. Use thumb for tiny contexts. Always include og in page meta where available.

Video Watermarking

Video processing produces two separate sets of variants: clean variants for streaming, and a watermarked variant for download. They are different keys in the variants map.

Context Clean variants Watermarked variant Watermark style Cycle
SOCIAL_VIDEO 360p_clean, 720p_clean, 1080p_clean 720p_watermarked (or 360p_watermarked) Diagonal 2-point: NexGate logo + @username overlay Every 5 seconds, alternates between upper-left and lower-right
PRODUCT_VIDEO 360p_clean, 720p_clean, 1080p_clean 720p_watermarked (or 360p_watermarked) Text-only (NexGate label) cycling all 4 corners Every 3 seconds
DM_VIDEO 360p_clean, 720p_clean None No watermark —

Which watermarked key do you get?

  • If the source video is tall/wide enough for 720p → key is 720p_watermarked
  • If the source is smaller (e.g. a 360p source) → key is 360p_watermarked
  • Always check which key is present rather than assuming 720p

When to use which:

  • Use 360p_clean / 720p_clean / 1080p_clean for in-app streaming and playback
  • Use 720p_watermarked / 360p_watermarked when you want to offer a download of the video — the watermark protects the content

Social video outro: SOCIAL_VIDEO files have a personalized branded outro clip appended (username + orange accent, no re-encode). The outro is baked into the 720p_watermarked variant only, not the clean variants.

The authenticated user's username is passed to FileThunder automatically by the backend — you send nothing extra for this.

Video Variants — Short Clips (< 3 minutes)

Key Format Typical Use
360p_clean MP4 URL First available at LIVE_PARTIAL — use for in-app streaming immediately
720p_clean MP4 URL Standard quality in-app streaming
1080p_clean MP4 URL HD in-app streaming (only present if source is 1080p-capable)
720p_watermarked MP4 URL Watermarked download variant — offer this for user downloads
360p_watermarked MP4 URL Watermarked download fallback — present instead of 720p_watermarked when source is too small
preview MP4 URL Auto-generated 3-second silent preview clip (speed-doubled from 6s of footage at ~5% into the video) — use for hover previews on cards
poster WebP URL Best auto-selected frame — show as video thumbnail before play
thumb WebP URL Small thumbnail for cards and grids
og WebP URL 1200×630 Open Graph image
blurhash String BlurHash string for placeholder
lqip data URI Inline WebP placeholder, no extra request
dominant_color Hex string Background tint for skeleton screens

Video Variants — Long Form (≥ 3 minutes, HLS)

Key Format Typical Use
master HLS master playlist URL Default — use this for all playback. Plug into HLS.js or native <video> on Safari; the player handles quality switching automatically based on bandwidth
360p_playlist HLS per-rendition playlist URL Only use when building a manual quality selector — swap the player src to this to force 360p
720p_playlist HLS per-rendition playlist URL Only use when building a manual quality selector — swap the player src to this to force 720p
1080p_playlist HLS per-rendition playlist URL Only use when building a manual quality selector — swap the player src to this to force 1080p (only present if source is 1080p-capable)
preview MP4 URL 3-second preview clip for card hover effects
poster WebP URL Best auto-selected frame
thumb WebP URL Card thumbnail
og WebP URL Open Graph image
blurhash String BlurHash placeholder
lqip data URI Inline placeholder
dominant_color Hex string Background tint

HLS Note: Always use the master key for adaptive streaming — it switches automatically between 360p/720p/1080p based on viewer bandwidth. Long-form videos do not include an MP4 fallback — if the environment does not support HLS, you will need to inform the user or handle it at the player level (e.g. HLS.js handles this for most browsers). Long-form videos do not produce a watermarked download variant — downloads of long videos are not supported.

The Upload Flow — Step by Step

Step 1 — Request a presigned upload URL (backend)

Call POST /api/v1/files/request-upload with the file metadata. You get back a fileId and a presignedUrl.

Step 2 — Upload the file directly to object storage (MinIO/CDN)

Make an HTTP PUT request to the presignedUrl with the file bytes as the body. This request does not go to the backend — it goes directly to object storage. Use XMLHttpRequest (not fetch) if you want to track upload progress, because XHR exposes an upload.onprogress event that fetch does not.

The request must include:

  • Content-Type header matching exactly the mimeType you sent in Step 1
  • The raw file bytes as the body (no multipart, no form data)
  • No Authorization header — the presigned URL is self-authenticating

A successful upload returns HTTP 200 with an empty body.

Upload progress tracking via XHR: XHR fires upload.onprogress events with loaded (bytes sent) and total (total bytes). Divide loaded / total to get a 0–1 progress value for your progress bar. This tracks network transfer progress, not processing progress. The progress bar should complete at 100% when the PUT returns 200, then transition to the processing state UI.

Step 3 — Track processing progress (SSE or polling)

After the PUT succeeds, open an SSE stream to GET /api/v1/files/progress/{fileId}. You will receive server-sent events as FileThunder processes the file. Close the stream when you receive READY or FAILED.

If SSE is inconvenient in your environment, use GET /api/v1/files/status/{fileId} to poll instead. Recommended polling interval: every 2–3 seconds.

Step 4 — Entity response contains the variants

Once READY, the entity API (product, shop, post, etc.) will include the variant map in its response. You do not need to call any file endpoint to get URLs — they come embedded in the entity response.

Endpoints

1. Request Upload URL

Purpose: Generate a presigned PUT URL and a fileId for a new file upload. Always call this before any file upload.

Endpoint: POST {base_url}/files/request-upload

Access Level: 🔒 Protected (Requires authenticated user)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>
Content-Type string Yes application/json

Request JSON Sample:

{
  "context": "PRODUCT_IMAGE",
  "originalFilename": "shoe-red-side.jpg",
  "mimeType": "image/jpeg",
  "fileSizeBytes": 2457600
}

Request Body Parameters:

Parameter Type Required Description Validation
context string Yes The purpose of this file — determines processing pipeline and storage bucket Must be one of the valid context values listed in the File Contexts section
originalFilename string Yes Original name of the file including extension Max 255 characters
mimeType string Yes MIME type of the file exactly as the browser reports it Must match the context's accepted formats; see File Format & Size Constraints
fileSizeBytes number Yes File size in bytes Must be a positive integer

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Upload URL generated",
  "action_time": "2026-06-21T14:22:10",
  "data": {
    "fileId": "a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556",
    "presignedUrl": "https://storage.nexgate.com/nexgate-raw/products/.../shoe-red-side.jpg?X-Amz-Signature=...",
    "expiresInSeconds": 3600
  }
}

Success Response Fields:

Field Description
data.fileId UUID identifying this file — save this, you will need it for SSE tracking and to associate the file with an entity
data.presignedUrl The URL to PUT the file bytes to — send directly to this URL, do not proxy through your server
data.expiresInSeconds How many seconds before the presigned URL expires (typically 3600 = 1 hour) — start the upload immediately

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "context is required. Valid values: SOCIAL_IMAGE, SOCIAL_VIDEO, PROFILE_PICTURE, ...",
  "action_time": "2026-06-21T14:22:10",
  "data": "context is required."
}

Standard Error Types:

  • 400 BAD_REQUEST — Missing or invalid context
  • 401 UNAUTHORIZED — Missing or expired Bearer token
  • 422 UNPROCESSABLE_ENTITY — Missing required fields

2. Upload File to Object Storage (Presigned PUT)

Purpose: Upload the raw file bytes directly to object storage using the presigned URL from Step 1. This is not a backend endpoint — it is a direct PUT to the object storage URL. It is documented here because understanding this step is essential to the flow.

Endpoint: PUT {presignedUrl} (the full URL returned in Step 1)

Access Level: 🌐 Self-authenticated (The presigned URL carries authentication in its query parameters — no Authorization header needed or allowed)

Request Headers:

Header Type Required Description
Content-Type string Yes Must exactly match the mimeType sent in Step 1 — e.g. image/jpeg, video/mp4

Request Body: Raw file bytes. No multipart encoding. No form fields. Just the file content.

Upload Progress:

Use XMLHttpRequest for this PUT request to gain access to upload progress events. The XMLHttpRequest.upload object fires progress events containing:

Property Type Description
loaded number Bytes sent so far
total number Total bytes to send (equals your fileSizeBytes)

Divide loaded / total to get a 0–1 ratio for a progress bar. This tracks network transfer only — once the PUT returns 200, transition the UI to the "Processing…" state and begin tracking via SSE (Step 3).

Success Response: HTTP 200 with an empty body. No JSON.

Failure Responses:

Status Cause
400 Content-Type header does not match what was declared in Step 1
403 Presigned URL has expired — go back to Step 1 and request a new one
413 File exceeds the size declared in fileSizeBytes in Step 1

3. Stream File Processing Progress (SSE)

Purpose: Receive real-time server-sent events as FileThunder processes the uploaded file. Open this stream immediately after the PUT in Step 2 returns 200. The stream closes automatically when READY or FAILED is reached.

Endpoint: GET {base_url}/files/progress/{fileId}

Access Level: 🔒 Protected (Only the file owner can stream progress for a given fileId)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>
Accept string Yes text/event-stream

Path Parameters:

Parameter Type Required Description Validation
fileId UUID Yes The fileId returned in Step 1 Must be a valid UUID owned by the authenticated user

Response: This endpoint returns a stream of Server-Sent Events, not a JSON body. Each event has a name (the status) and data (JSON payload).

SSE Event Format:

event: PROCESSING
data: {"status":"PROCESSING","fileId":"a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556"}

event: LIVE_PARTIAL
data: {"status":"LIVE_PARTIAL","fileId":"a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556"}

event: READY
data: {"status":"READY","fileId":"a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556"}

SSE Event Sequence:

Short video:

PENDING → UPLOADING → UPLOADED → PROCESSING → LIVE_PARTIAL → READY

Image:

PENDING → UPLOADING → UPLOADED → PROCESSING → READY

Long video (≥ 3 minutes):

PENDING → UPLOADING → UPLOADED → PROCESSING → LIVE_PARTIAL → READY

Digital product or DM document:

PENDING → UPLOADING → UPLOADED → SCANNING → READY

Event Handling:

Event name Action
PENDING Show spinner
UPLOADING Show spinner (XHR progress bar already running from Step 2)
UPLOADED Show "Processing…" state
SCANNING Show "Scanning for safety…" state
PROCESSING Show "Processing…" state
LIVE_PARTIAL Video 360p is available — can begin playback, show "HD loading" badge
READY Close the SSE connection. Show success. Refresh entity data.
FAILED Close the SSE connection. Show error. Offer re-upload.

SSE Timeout: The stream has a 5-minute server-side timeout. If your file is still processing after 5 minutes (large video), reconnect to this endpoint — it will immediately send the current status snapshot before continuing to stream.

Error Responses:

  • 401 UNAUTHORIZED — Invalid or missing token
  • 404 NOT_FOUND — fileId not found or does not belong to the authenticated user

4. Poll File Processing Status

Purpose: An alternative to SSE for environments where persistent connections are difficult (e.g. React Native background states, certain browser extensions). Returns the current processing status as a single JSON response. Poll every 2–3 seconds; stop when ready is true or failed is true.

Endpoint: GET {base_url}/files/status/{fileId}

Access Level: 🔒 Protected (Only the file owner)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>

Path Parameters:

Parameter Type Required Description Validation
fileId UUID Yes The fileId returned in Step 1 Must be a valid UUID owned by the authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Status retrieved",
  "action_time": "2026-06-21T14:23:45",
  "data": {
    "fileId": "a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556",
    "status": "PROCESSING",
    "ready": false,
    "failed": false,
    "processing": true
  }
}

Success Response Fields:

Field Type Description
data.fileId UUID The file identifier
data.status string Current status — one of PENDING, UPLOADING, UPLOADED, SCANNING, PROCESSING, LIVE_PARTIAL, READY, FAILED
data.ready boolean true when file is fully processed and variants are available
data.failed boolean true when processing failed — stop polling and show error
data.processing boolean true while processing is in progress — continue polling

Ready state response:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Status retrieved",
  "action_time": "2026-06-21T14:24:10",
  "data": {
    "fileId": "a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556",
    "status": "READY",
    "ready": true,
    "failed": false,
    "processing": false
  }
}

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "File not found or access denied",
  "action_time": "2026-06-21T14:24:10",
  "data": "File not found or access denied"
}

Standard Error Types:

  • 401 UNAUTHORIZED — Invalid or missing token
  • 404 NOT_FOUND — fileId not found or does not belong to authenticated user

5. Replace Video Thumbnail

Purpose: Upload a custom thumbnail image to replace the auto-selected thumbnail for a video file. Call this after the video has reached READY status. Returns a presigned URL — upload the image bytes to it (same pattern as Step 2 above).

Endpoint: POST {base_url}/files/thumbnail/{fileId}

Access Level: 🔒 Protected (Only the video owner)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>

Path Parameters:

Parameter Type Required Description Validation
fileId UUID Yes The fileId of the video whose thumbnail you want to replace Must be a valid video file owned by the authenticated user

Request Body: None — this is a POST with no body.

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Thumbnail upload URL generated",
  "action_time": "2026-06-21T14:25:00",
  "data": {
    "fileId": "a3f7c21b-09d4-4e8b-bf12-3c7d09e1f556",
    "presignedUrl": "https://storage.nexgate.com/nexgate-raw/products/.../thumb-a3f7c21b.jpg?X-Amz-Signature=...",
    "expiresInSeconds": 3600
  }
}

Success Response Fields:

Field Description
data.fileId The video file's ID
data.presignedUrl PUT the thumbnail image bytes here — same process as the main upload in Step 2
data.expiresInSeconds Seconds until the presigned URL expires

After uploading: PUT image/jpeg or image/png bytes to the presignedUrl. FileThunder will generate the thumbnail variants and update the video's effective thumbnail. Refresh the entity response to get the updated thumbnail URLs.

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2026-06-21T14:25:00",
  "data": "Token has expired"
}

Standard Error Types:

  • 401 UNAUTHORIZED — Invalid or missing token
  • 404 NOT_FOUND — fileId not found

6. List Digital Files Available for Download (Order)

Purpose: For a purchased digital product order, list all the files the buyer is entitled to download, along with download availability and remaining download counts.

Endpoint: GET {base_url}/e-commerce/orders/{orderId}/downloads

Access Level: 🔒 Protected (Only the order buyer)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>

Path Parameters:

Parameter Type Required Description Validation
orderId UUID Yes The order ID containing digital files Must be an order owned by the authenticated buyer

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "3 file(s) available for download",
  "action_time": "2026-06-21T14:26:00",
  "data": [
    {
      "fileId": "b9c1d33e-22f4-4a0b-9e67-1d4f22c3a881",
      "fileName": "nexgate-design-kit-v2.zip",
      "contentType": "application/zip",
      "fileSize": 52428800,
      "downloadCount": 1,
      "downloadsRemaining": 4,
      "accessExpiresAt": "2026-12-21T00:00:00",
      "canDownload": true
    },
    {
      "fileId": "c2e5f44a-33g5-5b1c-af78-2e5g33d4b992",
      "fileName": "user-manual.pdf",
      "contentType": "application/pdf",
      "fileSize": 1048576,
      "downloadCount": 0,
      "downloadsRemaining": 5,
      "accessExpiresAt": "2026-12-21T00:00:00",
      "canDownload": true
    }
  ]
}

Success Response Fields:

Field Type Description
[].fileId UUID File identifier — use this in the next endpoint to get a download URL
[].fileName string Original filename including extension
[].contentType string MIME type of the file
[].fileSize number File size in bytes
[].downloadCount number How many times the buyer has already downloaded this file
[].downloadsRemaining number How many more downloads the buyer is allowed
[].accessExpiresAt string ISO 8601 datetime after which download access expires
[].canDownload boolean false if download limit reached or access has expired — show disabled button

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Order not found",
  "action_time": "2026-06-21T14:26:00",
  "data": "Order not found"
}

Standard Error Types:

  • 400 BAD_REQUEST — Order does not contain digital files, or buyer access is expired
  • 401 UNAUTHORIZED — Invalid or missing token
  • 404 NOT_FOUND — Order not found or does not belong to authenticated user

7. Generate Digital File Download URL

Purpose: Generate a time-limited, single-use download URL for a specific digital file in an order. Call this endpoint when the user clicks the download button — do not cache this URL. Open it immediately in a new tab or trigger a browser download.

Endpoint: GET {base_url}/e-commerce/orders/{orderId}/downloads/{fileId}

Access Level: 🔒 Protected (Only the order buyer)

Authentication: Bearer Token — Authorization: Bearer <token>

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <your_jwt_token>

Path Parameters:

Parameter Type Required Description Validation
orderId UUID Yes The order ID Must belong to the authenticated buyer
fileId UUID Yes The specific file to download (from endpoint 6) Must be a file within the specified order

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Download URL generated — link expires in 15 minutes",
  "action_time": "2026-06-21T14:27:00",
  "data": {
    "fileId": "b9c1d33e-22f4-4a0b-9e67-1d4f22c3a881",
    "fileName": "nexgate-design-kit-v2.zip",
    "downloadUrl": "https://storage.nexgate.com/nexgate-digital/products/.../nexgate-design-kit-v2.zip?X-Amz-Signature=...&X-Amz-Expires=300",
    "expiresAt": "2026-06-21T14:32:00",
    "downloadsRemaining": 3,
    "downloadCount": 2
  }
}

Success Response Fields:

Field Type Description
data.fileId UUID File identifier
data.fileName string Filename to use when saving locally
data.downloadUrl string Pre-signed download URL — valid for 15 minutes only. Open immediately. Do not cache.
data.expiresAt string ISO 8601 datetime when the download URL expires
data.downloadsRemaining number How many downloads remain after this one
data.downloadCount number Total downloads made so far including this one

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Download limit reached for this file",
  "action_time": "2026-06-21T14:27:00",
  "data": "Download limit reached for this file"
}

Standard Error Types:

  • 400 BAD_REQUEST — Download limit reached, access expired, or buyer is not eligible
  • 401 UNAUTHORIZED — Invalid or missing token
  • 404 NOT_FOUND — Order or file not found

How Variants Appear in Entity Responses

You never call a dedicated endpoint to get variant URLs. When an entity (product, post, shop, profile, event) is fetched via its own API, the response already contains the assembled variant map. Here is what to expect per entity type:

Product Image Variants

{
  "productImageVariants": [
    {
      "large": "https://cdn.nexgate.com/products/owner123/fileabc/large.webp",
      "medium": "https://cdn.nexgate.com/products/owner123/fileabc/medium.webp",
      "thumb": "https://cdn.nexgate.com/products/owner123/fileabc/thumb.webp",
      "og": "https://cdn.nexgate.com/products/owner123/fileabc/og.webp",
      "blurhash": "LGF5?xYk^6#M@-5c,1J5@[or[Q6",
      "lqip": "data:image/webp;base64,/9j/4AAQ...",
      "dominant_color": "#C8A882"
    }
  ]
}

productImageVariants is an array — one entry per uploaded image. Index 0 is the primary image.

Video Variants (short clip)

{
  "previewVariants": {
    "360p_clean": "https://cdn.nexgate.com/products/owner123/filevid/360p_clean.mp4",
    "720p_clean": "https://cdn.nexgate.com/products/owner123/filevid/720p_clean.mp4",
    "1080p_clean": "https://cdn.nexgate.com/products/owner123/filevid/1080p_clean.mp4",
    "720p_watermarked": "https://cdn.nexgate.com/products/owner123/filevid/720p_watermarked.mp4",
    "preview": "https://cdn.nexgate.com/products/owner123/filevid/preview_3s.mp4",
    "poster": "https://cdn.nexgate.com/products/owner123/filevid/poster.webp",
    "thumb": "https://cdn.nexgate.com/products/owner123/filevid/thumb.webp",
    "og": "https://cdn.nexgate.com/products/owner123/filevid/og.webp",
    "blurhash": "LGF5?xYk^6#M@-5c,1J5@[or[Q6",
    "lqip": "data:image/webp;base64,/9j/4AAQ...",
    "dominant_color": "#1A1A2E"
  }
}

If the source video was too small for 720p, 720p_watermarked will be absent and 360p_watermarked will be present instead. Always check which watermarked key exists before rendering a download button.

Video Variants (long form / HLS)

{
  "previewVariants": {
    "master": "https://cdn.nexgate.com/products/owner123/filevid/hls/master.m3u8",
    "360p_playlist": "https://cdn.nexgate.com/products/owner123/filevid/hls/360p/360p.m3u8",
    "720p_playlist": "https://cdn.nexgate.com/products/owner123/filevid/hls/720p/720p.m3u8",
    "1080p_playlist": "https://cdn.nexgate.com/products/owner123/filevid/hls/1080p/1080p.m3u8",
    "preview": "https://cdn.nexgate.com/products/owner123/filevid/preview_3s.mp4",
    "poster": "https://cdn.nexgate.com/products/owner123/filevid/poster.webp",
    "thumb": "https://cdn.nexgate.com/products/owner123/filevid/thumb.webp",
    "og": "https://cdn.nexgate.com/products/owner123/filevid/og.webp",
    "blurhash": "LGF5?xYk^6#M@-5c,1J5@[or[Q6",
    "lqip": "data:image/webp;base64,/9j/4AAQ...",
    "dominant_color": "#1A1A2E"
  }
}

Feed master into HLS.js or a native <video> src on Safari. Long-form videos do not include an MP4 fallback and do not have a watermarked download variant.

LIVE_PARTIAL state (video still processing)

When you get an entity response while the video is in LIVE_PARTIAL:

  • Short clips: only 360p_clean is present alongside the thumbnail keys. Higher resolutions and the watermarked variant arrive once READY.
  • Long form (HLS): only 360p_playlist and master (pointing to the 360p-only rendition) are present. Additional renditions and thumbnail keys arrive once READY.

You can safely begin playback in both cases and show a "HD loading" badge.

Null variants

If a file is still in PROCESSING and you fetch the entity, variants fields may be null or an empty array. Always null-check before rendering. Display a placeholder (blurhash, dominant_color, or a skeleton) until variants are available.

Best Practices

Upload

  • Always validate before requesting a presigned URL. Check file size and MIME type on the client before making the Step 1 request. Rejecting obvious bad inputs early avoids wasted presigned URL slots.
  • Start the SSE connection before the PUT finishes. Open the SSE stream as soon as you receive fileId, so you do not miss early status events like UPLOADING.
  • Never proxy the file through your frontend server. The presigned URL uploads directly to object storage. Do not relay bytes through a backend API route.
  • Handle presigned URL expiry. If a user leaves the upload screen and comes back, the presigned URL may have expired. Call Step 1 again to get a fresh one.
  • Send exactly the declared mimeType as Content-Type in the PUT. A mismatch causes a 400 from object storage.

Progress UI

  • Use XHR upload progress for the bytes-in-flight phase (Step 2). Show a numeric percentage or progress bar.
  • Transition to a spinner or indeterminate progress at 100% upload — processing time is unpredictable.
  • For short images, processing is usually 2–5 seconds.
  • For short videos (< 3 min), processing typically takes 30 seconds to 2 minutes.
  • For long videos (≥ 3 min), processing can take 5–15 minutes. Show LIVE_PARTIAL content early at 360p with an overlay badge.
  • On FAILED, offer a clear re-upload action — do not auto-retry silently.

SSE vs Polling

Use SSE when Use polling when
Web browser context React Native / mobile apps
Single in-progress upload screen Background upload (app minimised)
You can keep the tab open Network conditions drop connections often

SSE is preferred — it is lower overhead and gives instant events. Polling at 2-second intervals is a reliable fallback.

Variants

  • Always show a placeholder first. Use lqip as an inline src or apply blurhash as a CSS background immediately — before the real image loads.
  • Use dominant_color as the background tint on skeleton screens and image containers before any image variant is available.
  • Use medium for feed cards and grids, not large. large is for detail views and lightboxes only.
  • Always set og in Open Graph meta tags when rendering shareable pages (products, posts, events).
  • For HLS video, prefer master.m3u8 on supported browsers. Long-form videos have no MP4 fallback — use HLS.js to cover non-native HLS environments (most Android browsers, older Chrome).
  • Do not hardcode or cache variant URLs. They come from entity responses. If a CDN or storage URL base changes, your app automatically picks up the new URLs without any code change.

Digital Downloads

  • Never store download URLs. They expire in 15 minutes. Always call endpoint 7 on each user-initiated download click.
  • Check canDownload from endpoint 6 before showing the download button. If false, show a disabled button with a reason ("Download limit reached" or "Access expired").
  • Open the downloadUrl in a new browser tab or trigger a native download — do not fetch() it through your app.
  • Re-fetch endpoint 6 after each download to update the downloadsRemaining count shown to the user.

Quick Reference

Context → Variants Cheat Sheet

Context Variants Generated
SOCIAL_IMAGE large, medium, thumb, og, blurhash, lqip, dominant_color
SOCIAL_VIDEO (short) 360p_clean, 720p_clean, 1080p_clean, 720p_watermarked (or 360p_watermarked), preview, poster, thumb, og, blurhash, lqip, dominant_color
SOCIAL_VIDEO (long) master, 360p_playlist, 720p_playlist, 1080p_playlist, preview, poster, thumb, og, blurhash, lqip, dominant_color
PROFILE_PICTURE medium, thumb, blurhash, lqip
COVER_PHOTO large, thumb, og, blurhash, lqip
DM_IMAGE medium, thumb, blurhash, lqip
DM_VIDEO 360p_clean, 720p_clean
DM_DOCUMENT (none — secure download only)
PRODUCT_IMAGE large, medium, thumb, og, blurhash, lqip, dominant_color
PRODUCT_VIDEO (short) 360p_clean, 720p_clean, 1080p_clean, 720p_watermarked (or 360p_watermarked), preview, poster, thumb, og, blurhash, lqip, dominant_color
PRODUCT_VIDEO (long) master, 360p_playlist, 720p_playlist, 1080p_playlist, preview, poster, thumb, og, blurhash, lqip, dominant_color
DIGITAL_PRODUCT (none — secure download only)
SHOP_BANNER large, thumb, og, blurhash, lqip
SHOP_LOGO medium, thumb, blurhash, lqip
EVENT_COVER large, medium, thumb, og, blurhash, lqip
EVENT_GALLERY large, medium, thumb, blurhash, lqip

Status Codes

Code Meaning
200 OK Success
400 BAD_REQUEST Invalid request data, limit reached, or item already exists
401 UNAUTHORIZED Missing, expired, or invalid token
403 FORBIDDEN Authenticated but not permitted (not the file owner, not the buyer)
404 NOT_FOUND File, order, or resource not found
422 UNPROCESSABLE_ENTITY Validation error — response data will contain field-level error messages
500 INTERNAL_SERVER_ERROR Server error — report to backend team with action_time

Authentication

All endpoints require: Authorization: Bearer <your_jwt_token>

Tokens are obtained from the auth endpoints (see Auth API documentation). A 401 means the token is expired or invalid — redirect the user to login.

No comments to display

Back to top