1. Create an application and install the SDK

In the Serve dashboard, create an application and generate an API key for it. Use Node.js 20+ or Bun. The env-file command below requires Node.js 20.6+.

npm install @skycanvasstudio/serve-server

Install released versions from npm. To test an unreleased local build, install the verified .tgz artifacts from npm_pkg/artifacts instead.

2. Add these to your app's .env.local

# Your consuming app needs these two values. Never use a public prefix for the key.
FILE_SERVER_URL=https://files.example.com
FILE_SERVER_API_KEY=sk_replace_with_your_application_key

Use the public origin of your Serve installation, for example https://files.example.com or http://localhost:5000. Do not append /api or a file path. Restart your app after changing env variables.

These variables belong to the consuming app. Keep the API key server-only: never add NEXT_PUBLIC_, VITE_, or another public prefix.

3. Save upload.mjs and run it

import { createFileServer } from "@skycanvasstudio/serve-server";

const files = createFileServer({
  baseUrl: process.env.FILE_SERVER_URL,
  apiKey: process.env.FILE_SERVER_API_KEY,
});

const asset = await files.files.upload({
  file: new Blob(["Hello from Serve"], { type: "text/plain" }),
  filename: "hello.txt",
});

console.log("File URL:", asset.urls.content);

node --env-file=.env.local upload.mjs

Expected result: a public file URL on your Serve domain. Open it to see Hello from Serve. A File supplies its filename; Blob and buffer uploads need an explicit filename.

Use the returned URLs

Use asset.urls.content for downloads, video and audio. Use asset.urls.image or the React AdvancedImage component for images and resizing. Preserve the asset ID in your app when you need to retrieve or delete it later.

Browsers request these URLs from Serve. Serve reads your configured local or S3 storage and handles byte ranges and image transformations. Do not construct bucket URLs or expose storage credentials. A CDN can sit in front of the Serve domain later.

Delivered content is public. API keys and browser tokens protect upload and management operations, not access to a known file URL.