How SyncSnap works
This page walks through the flow from your web app to the uploaded file.Overview
1
Create a job
Your backend calls the SyncSnap API (via the
syncsnap server SDK) to create a job. Each job has a unique ID and starts in pending status.2
Show the QR code
Your frontend receives the job ID and displays a QR code. The QR code encodes a URL like
https://upload.syncsnap.xyz/?job_id=<jobId>. Use createUploadUrl(jobId, { baseUrl }) from @syncsnap/react to build this URL.3
User scans and uploads
The user scans the QR code with their phone. Their browser opens the SyncSnap upload page. They select a file and upload it. The SyncSnap service associates the file with the job and sets the job status to
completed (or failed on error).4
Wait for completion
Your frontend calls the wait endpoint (e.g.
GET /api/syncsnap/job/:id/wait). Your backend runs server-side polling until the job is completed or failed, then returns the final job and a result (e.g. presigned download URL or custom payload from your onCompleted callback). The client receives this in useSyncsnapJob’s onCompleted(job, result).API routes your backend must expose
The React SDK expects your app to expose these endpoints (thesyncsnap Next.js helper implements them via a single catch-all route):
The base path (
/api/syncsnap) is configurable on the client via createJobUrl, getJobUrl, and getWaitForCompletionUrl in useSyncsnapJob.
Job statuses
Your frontend typically calls the wait endpoint once; the server polls the job and returns when it’s done, so the client doesn’t poll itself.
Security
- API key: Your server uses a SyncSnap API key (e.g.
SYNCSNAP_TOKEN) to create jobs and get download URLs. Never expose this key to the browser. - Presigned URLs: Download URLs are short-lived. Your backend requests them from SyncSnap and forwards them to your frontend so the client never talks to SyncSnap directly with the API key.