Uploading assets

An asset is content submitted to CalmLens for analysis. You can create one from a file's bytes, from inline content, from a remote URL, or in sequential parts for larger uploads. This guide shows each upload mode, the limits that apply, and how to attach metadata and folders. For every field and error code, see the Assets API reference.

Requests authenticate with a project API key sent from your server. See Authentication.

Upload with an SDK

For files, pass a file, buffer or stream to your SDK. It selects the upload mode and handles authentication.

import { readFile } from "node:fs/promises";
import { CalmLensClient } from "@calmlens/sdk";

const client = new CalmLensClient({
  apiKey: process.env.CALMLENS_API_KEY!,
  projectId: process.env.CALMLENS_PROJECT_ID!,
});

const asset = await client.assets.create({
  name: "cat.jpg",
  visibility: "private",
  processingOptions: { keepContentAfterProcessing: true },
  content: {
    buffer: await readFile("./cat.jpg"),
    type: "image/jpeg",
  },
});

Waiting for the decision

Choose either flow independently of the upload mode:

Text and images support both flows. Audio and video always run asynchronously and return pending, even with queue=false. A multipart upload uses the queue mode chosen when it starts: CalmLens saves it with the upload, so whichever client sends the final part gets the same behaviour. See Queue mode.

For queued uploads, save the asset ID and configure a webhook for asset.classified and asset.failed. Keep content unpublished until approved; a successful upload alone is not a moderation decision.

Completed assets use the nested report described in Report format. Check each category's status before reading score.

See Asset lifecycle for each status and how to wait for a queued asset, and Delivering assets to serve asset content, create signed URLs for private assets, and apply lenses.

Fallback when webhooks are unavailable

If your integration cannot receive webhooks, retrieve the asset periodically with client.assets.retrieve({ assetId }). This requires a retry loop in your application; the retrieval call does not wait for classification.

Start with a short delay, increase it between checks using exponential backoff, and cap the interval. Set an overall timeout so checks cannot continue indefinitely. Stop when the status is approved, rejected or error; keep content unpublished while it is pending. If the timeout expires, treat the result as unresolved and keep the content unpublished.

client.assets.retrieve({ assetId })

Upload modes

Choosing a mode

The SDKs choose the mode for you: they stream files with direct binary or multipart uploads and send other inputs as JSON.

Direct binary upload

For direct HTTP integrations, send the unencoded file to POST /projects/:projectId/assets/upload. Metadata goes in query parameters. The Assets reference documents the complete request.

JSON upload

POST /projects/:projectId/assets remains available for base64, plain-text, and remote URL submissions.

• Direct image uploads must be smaller than 10MB.
• All other file types support up to 5GB.
• The request body can contain content.base64, content.plainText, or url.

JSON upload with base64 content

import { CalmLensClient } from "@calmlens/sdk";

const client = new CalmLensClient({
  apiKey: "your-api-key",
  projectId: "your-project-id"
});

const response = await client.assets.create({
  "name": "cat.png",
  "description": "Homepage hero image",
  "visibility": "private",
  "processingOptions": {
    "keepContentAfterProcessing": true
  },
  "content": {
    "base64": "your-base64-file",
    "type": "image/png"
  }
});

Plain text upload

import { CalmLensClient } from "@calmlens/sdk";

const client = new CalmLensClient({
  apiKey: "your-api-key",
  projectId: "your-project-id"
});

const response = await client.assets.create({
  "name": "notes.txt",
  "content": {
    "plainText": "This is the extracted text to moderate.",
    "type": "text/plain"
  }
});

Remote URL upload

Remote URLs must use HTTP or HTTPS. Private IP addresses, localhost names and URL credentials are rejected, and each redirect is checked. Downloads time out after 30 seconds and are limited to 10 MB for images and 20 MB for other files. Use multipart upload for larger files.

import { CalmLensClient } from "@calmlens/sdk";

const client = new CalmLensClient({
  apiKey: "your-api-key",
  projectId: "your-project-id"
});

const response = await client.assets.create({
  "name": "landing-page",
  "url": "https://example.com"
});

Multipart upload

The SDK chooses multipart uploads when needed. For manual chunks, ordering, finalisation and recovery, see Multipart uploads.

Retrying uploads

Each successful upload creates an asset that counts toward your usage, and a request that timed out may still have succeeded. Send an Idempotency-Key header with a unique value, such as a UUID, and reuse it when you retry: if the first request succeeded, CalmLens returns its response instead of creating a second asset. An externalId is also unique within a project, so a retry that reuses one is refused with 409 asset/duplicate-external-id rather than creating a duplicate. See Retrying requests safely.

Asset types and limits

CalmLens detects the asset type from the content's MIME type.

Image uploads are also constrained by a maximum image dimension of 12,000 x 12,000 pixels.

Asset metadata

Attach custom fields to your uploads. See Asset metadata for field definitions and examples.

Folders

Pass a folderId to organise an upload. See Folders for creating, moving and managing a folder tree.