event.target.files?.[0] && void upload(event.target.files[0])} />
);
}
```
The same request without progress:
```ts
await fetch(uploadUrl, {
method: "PUT",
headers: { "Content-Type": "application/octet-stream" },
body: file,
});
```
#### Step 3: complete the upload on your server
The completion route checks that the session belongs to the signed-in user, completes it, waits for finalization and the malware scan, and returns the link.
```ts title="app/api/uploads/[sessionId]/complete/route.ts"
import { SteadyLink, SteadyLinkError, SteadyLinkTimeoutError } from "@steadylink/sdk";
import { getCurrentUser } from "@/lib/auth";
const steadylink = new SteadyLink({ apiKey: process.env.STEADYLINK_API_KEY! });
export async function POST(request: Request, { params }: { params: Promise<{ sessionId: string }> }) {
const user = await getCurrentUser();
if (!user) return Response.json({ error: "Sign in to upload" }, { status: 401 });
const { sessionId } = await params;
const { batchId } = await request.json();
// Only complete sessions this user created: their folder is part of the session.
const batch = await steadylink.getUploadBatch(batchId);
const session = batch.files.find((file) => file.id === sessionId);
if (!session || session.path !== `users/${user.id}/`) {
return Response.json({ error: "Upload not found" }, { status: 404 });
}
try {
await steadylink.completeUpload(sessionId); // sends Idempotency-Key: complete-{sessionId}
const finished = await steadylink.waitForUploads(batchId, [sessionId], { timeoutMs: 60_000 });
const file = finished.files.find((item) => item.id === sessionId)!;
if (file.status !== "ready") {
return Response.json({ error: file.error?.message ?? `Upload ${file.status}` }, { status: 422 });
}
return Response.json({ assetId: file.objectAssetId, url: steadylink.link(file.objectAssetId!) });
} catch (error) {
if (error instanceof SteadyLinkTimeoutError) {
return Response.json({ error: "Still processing. Check again shortly." }, { status: 202 });
}
if (error instanceof SteadyLinkError) {
return Response.json({ error: error.message }, { status: error.status === 410 ? 410 : 502 });
}
throw error;
}
}
```
Notes on this step:
- **Completion is idempotent.** If the browser retries, `completeUpload` sends the same `Idempotency-Key`, and a session that already finished returns its final state. That is why it is safe to call from a route the user can hit twice.
- **Waiting is optional.** You do not have to hold the request open while SteadyLink finalizes and scans the file. You can return right after `completeUpload` and let the browser poll a status route that calls `getUploadBatch`, or listen for the `upload.updated` server-sent events on `GET /api/events/stream` from your server.
- **Visibility.** New files take the destination bucket's default. For user content that should not be public, keep the bucket private and hand out [signed links](https://steadylink.io/docs/security/private-links). To make one file public, call `steadylink.setVisibility(BUCKET_ID, session.path + session.filename, "public")` after it is `ready`.
- **Size mismatches.** If the bytes the browser sent do not match the declared `size`, the session ends `failed` with `upload_size_mismatch`. This also catches a user picking a different file between steps.
#### Several files at once
One batch holds up to 100 sessions, each with its own `uploadUrl`. Send all the file descriptions in step 1, PUT each file to its own URL (two to four at a time is a good balance), and complete each session separately. A file that fails does not affect the others; the batch status ends `partial` if any file was blocked or failed.
#### When storage is unreachable
Some corporate networks block the storage host that presigned URLs point to while allowing your own domain. For those users you can route the bytes through your server, which forwards them to SteadyLink's API instead of storage:
```ts title="app/api/uploads/[sessionId]/content/route.ts"
import { SteadyLink } from "@steadylink/sdk";
const steadylink = new SteadyLink({ apiKey: process.env.STEADYLINK_API_KEY! });
export async function PUT(request: Request, { params }: { params: Promise<{ sessionId: string }> }) {
const { sessionId } = await params;
const batchId = new URL(request.url).searchParams.get("batch")!;
const batch = await steadylink.getUploadBatch(batchId);
const session = batch.files.find((file) => file.id === sessionId);
if (!session) return new Response("Not found", { status: 404 });
// Check ownership here exactly as in the completion route.
await steadylink.sendUploadBytes(session, request.body!, { via: "api" });
return new Response(null, { status: 204 });
}
```
`via: "api"` streams the bytes to `PUT /api/upload-sessions/{session_id}/content` with your API key, so it must run on your server. That route requires the body to be exactly the declared size, accepts bytes until the session's `expiresAt` (not just the 15-minute URL lifetime), and leaves the session `uploaded`, ready to complete as usual. The trade-off is that every byte now passes through your server, so your hosting platform's request size and duration limits apply. Use it as a fallback, not the default. The SDK's `upload()` and the CLI accept the same `via: "api"` option (`--via api`) for server-side scripts on restricted networks.
#### Troubleshooting
| Symptom | Cause |
| --- | --- |
| `403` from storage on the PUT | The `Content-Type` was not `application/octet-stream`, extra signed headers were added, or the URL is older than 15 minutes. Create a new session. |
| Session `failed` with `upload_size_mismatch` | The bytes sent differ from the declared `size`. |
| Session `failed` with `upload_missing` | Completion was called before the PUT finished, or the PUT never reached storage. |
| `410` from completion | The session expired. Create a new one. |
| `409 Idempotency key mismatch` | Completion was retried with a different `Idempotency-Key`. Reuse the first one. |
| `413` with `upload_size_limit` when creating the session | The file is larger than your plan or API key allows. |
| Session `blocked` | The file failed the malware scan or a bucket rule. Do not retry it. |
| `429` | Too many requests for your plan's rate limit. Retry after the `Retry-After` header. |
#### Next steps
- [Upload widget](https://steadylink.io/docs/guides/upload-widget): A no-code embed that does this whole flow for you, with review before publishing.
- [Uploads API](https://steadylink.io/docs/reference/api/uploads): Request and response details for every upload route.
- [TypeScript SDK](https://steadylink.io/docs/reference/sdk): `createUploadBatch`, `completeUpload`, `waitForUploads`, and `sendUploadBytes`.
### Website migration
Source: https://steadylink.io/docs/guides/website-migration
Website migration is for moving an existing site's media into SteadyLink without downloading and re-uploading it by hand. You give SteadyLink a starting URL; it crawls up to 200 pages on that site, lists every image, video, document, and download those pages reference, and checks whether each one still loads. You pick the files to keep, and an import job copies them into a bucket folder. The result is a CSV or JSON map from each original URL to its new stable link, which you use to update your site's source.
#### Before you start
- The site must be reachable on the public internet over HTTP or HTTPS on the standard ports (80 or 443). Addresses that resolve to private, loopback, link-local, multicast, or reserved ranges, `localhost`, and cloud metadata hosts are refused, including through redirects. A URL with a username or password in it is refused too.
- The crawler identifies itself as `SteadyLink-Migration-Scanner/1.0` and follows the site's `robots.txt`. Pages disallowed for that user agent are skipped. If your staging site blocks crawlers, allow this user agent for the duration of the scan.
- Decide which bucket and folder the files should land in. You can type a new folder path; it is created during the import.
#### Run a scan
**Start the scan**
Open **Migrate a site**, enter a domain or starting URL such as `northwind.example` or `https://northwind.example/products`, and start the scan. A bare domain is treated as `https://`. The dashboard scans up to 50 pages; use the API to scan up to 200.
**Wait for the report**
The scan runs in the background. Progress, pages scanned, and media found update as it goes. You can leave the page and come back through **History**.
**Review the report**
When the status is `complete`, the report lists every media URL found, with its type, size, status, and how many pages reference it.
```bash title="Start a scan with the API"
curl -X POST https://api.steadylink.io/api/migration-scans \
-H "X-API-Key: $STEADYLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://northwind.example", "maxPages": 200 }'
```
```json title="Response" status="202 Accepted"
{
"id": "a3c5e7f9-1b2d-4e6f-8a0c-2e4f6a8b0c1d",
"url": "https://northwind.example",
"status": "queued",
"maxPages": 200,
"pagesScanned": 0,
"mediaFound": 0,
"progress": 0,
"error": null,
"createdAt": "2026-10-08T15:20:44.019311",
"updatedAt": "2026-10-08T15:20:44.019311"
}
```
Poll `GET /api/migration-scans/{scan_id}` until `status` is `complete` or `failed`. `maxPages` accepts 1 to 200 and defaults to 50.
##### How the crawler explores
The crawl starts at your URL and follows links breadth-first, staying on the exact host you started on (`www.northwind.example` and `northwind.example` are different hosts). It stops when it has visited `maxPages` pages or runs out of links. Each page can be up to 3 MB; larger pages and pages that fail to load are skipped and do not stop the scan. Only HTML responses are read for references; other content types are skipped.
Media can live on any public host, such as a CDN or an old asset domain. The crawler records up to 5,000 distinct media URLs per scan.
##### What counts as media
| Reference | Recorded as |
| --- | --- |
| `{status}
{link && {link}}