File Uploads - Raykoi

How it works

A file field doesn’t submit its bytes as part of the JSON payload. Instead, the SDK:

Requests a short-lived signed upload URL for that specific field.
Uploads the file directly to storage, bypassing your server entirely.
Includes the resulting file reference in the submission payload in place of the raw file.

// This happens automatically inside form.submit() —
// shown here for what's actually going on under the hood.
const form = client.form('YOUR_PUBLIC_ID');

const fileRef = await form.upload('resume', file);
// fileRef: { path, originalFilename, mimeType, sizeBytes }

await form.submit({
  email: 'user@example.com',
  resume: fileRef,
});

If you’re using a framework adapter (useRaykoiForm) or client.form(id).submit() directly, you don’t write any of this — pass a File/FileList value under a field’s name and the SDK detects it, uploads it, and substitutes the reference automatically, with progress events available via onProgress.

Validation

Two layers, both enforced server-side (client-declared values are never trusted on their own):

Per-field, from the field’s own configuration in the form builder — maxSizeMB, allowedTypes (supports wildcards like image/*).
Per-workspace, from your plan — a per-file size ceiling and a total storage quota.

The stricter of the two always applies. After the file lands in storage, its actual reported size and MIME type are re-checked against both — a client that lies about Content-Type at upload time doesn’t get through on a technicality.

File uploads are not supported on the No-JS HTML path. The signed-URL flow is inherently a multi-step, JavaScript-orchestrated exchange — a browser navigating a plain <form> can only make one request, with no way to fetch a signed URL and PUT to it first.

Downloading a file

Files aren’t publicly accessible by path. Your backend requests a short-lived signed download URL through the Server Data API using your secret API key:

import { createAdminClient } from '@raykoi/sdk/admin';

const admin = createAdminClient({ apiKey: process.env.RAYKOI_SECRET_KEY });
const url = await admin.files.getDownloadUrl('YOUR_PUBLIC_ID', filePath);

​How it works

​Validation

​Downloading a file

How it works

Validation

Downloading a file