Upload presets

An upload preset is a saved set of upload settings with its own ID. Browsers and apps upload through it without an API key, and your server can upload through it too, so every upload of that kind follows the same rules. Manage presets in Portal › Upload presets. For a step-by-step setup, see the quick start.

Who can upload

Each preset accepts browser uploads in one of two ways:

New presets require a token. A preset open to anyone must have a daily upload limit.

Settings

A browser can only name and describe its upload. The folder, visibility, metadata, processing options and externalId come from the preset or the upload token; sending them from the browser fails with upload-preset/field-not-allowed.

Upload tokens

An upload token lets one browser upload through a preset that requires tokens. Sign tokens on your server with the JavaScript, Python, Go, Java, Ruby or Rust SDK. Signing happens locally with your API key and makes no request to CalmLens.

Each returns the token and when it expires, in milliseconds since the Unix epoch.

const { token, expiresAt } = await client.uploadTokens.sign({
  uploadPresetId: "your-upload-preset-id",
  externalId: "post-42",
  expiresInSeconds: 600,
});

Each token:

• uploads one asset. A second upload with it fails with upload-token/used; an upload that fails frees the token for a retry.
• starts an upload until it expires, and stays valid for that upload's later parts and status checks for up to a day.
• acts for the API key that signed it. The key must be able to create assets in the preset's folder. Revoking the key stops its tokens working.

Uploading from a browser

Only the JavaScript SDK runs in browsers and apps. Its CalmLensAppClient, from @calmlens/sdk/app, uploads through an upload preset instead of an API key:

<script type="module">
  import { CalmLensAppClient } from "@calmlens/sdk/app";

  const client = new CalmLensAppClient({
    uploadPresetId: "your-upload-preset-id",
    token: () => fetchTokenFromYourServer(), // only for presets that require a token
  });
</script>

This client has only assets.create, assets.moderate, assets.uploadPart and assets.retrieve, for its own uploads. They return the asset's id, name, uploadPresetId and createdAt, plus status when the preset shows decisions. It refuses an API key with sdk/invalid-config.

Over HTTP, browser uploads use the same bodies and query parameters as the project upload endpoints, under the preset's path, with the token as Authorization: Bearer <token>:

Uploading from your server through a preset

Pass uploadPresetId (upload_preset_id in Python and Ruby, UploadPresetID in Go, upload_preset_id in Rust) to client.assets.create() with your API key, in any SDK, to apply a preset's folder, visibility, file types and size limit. You can still set externalId, metadata and processing options. A folder or visibility that differs from the preset's fails with upload-preset/field-not-allowed.

Errors