Upload presets

Save shared upload settings in Portal › Upload presets. Each preset has an ID that browsers and apps can use without an API key; server uploads can use it too. Follow the quick start to set one up.

Who can upload

Each preset accepts browser uploads in one of two ways:

AccessHow a browser uploadsUse it for
Users your server approves (token)With an upload token your server signed for that uploadApps with sign-in; see Upload tokens
Anyone with the preset ID (anyone)With the preset ID alone, up to the preset's daily limit for each clientStatic sites, public forms and prototypes; see Upload without a server

New presets require a token. A preset open to anyone must have a daily upload limit. When a client reaches it, the organisation's owners are emailed, at most once a day for each preset.

Settings

SettingEffect
File typesMIME types the preset accepts, such as image/* or video/mp4. Empty accepts every supported type.
Maximum file sizeLargest file the preset accepts. Multipart uploads are checked as their parts arrive.
FolderFolder that uploads go into. Browser uploads can't choose another one.
Moderation policyPolicy that moderates uploads through the preset, such as a stricter one for a children's section of your app. By default uploads use the project's policy. Choose one of your organisation's policies; content extracted from an upload, such as a document's images, uses the same policy.
VisibilityVisibility of uploaded assets.
Keep content after moderationKeeps each uploaded file so you can serve it from the CDN. When off, the file is deleted once it's moderated and only its record and report remain.
Read text in imagesRuns OCR on uploaded images and moderates the text it finds as well.
Streaming PreviewPrepares an adaptive stream of uploaded audio and video. Needs content to be kept.
Show the decision to the uploaderWhen on, browser uploads see the moderation status of their own upload. Reports, metadata and URLs are never returned to the browser.
Daily upload limitMost browser uploads each client makes per UTC day. Clients are counted by IP address (IPv6 by /64 network), so one visitor can't use up the preset for everyone. Uploads from your server don't count against it.
Allowed sitesOrigins allowed to upload from the browser, such as https://example.com. When the list has sites, requests from other sites, or without an Origin header, are refused. Empty lets any site upload.
Accept uploadsTurn off to pause the preset without deleting it.

A browser can only name and describe its upload. The folder, visibility and processing options come from the preset, and externalId from the upload token. Presets have no metadata, and a browser can't send metadata, tags, authorId, context, externalUrl or processingOptions, or upload from a URL. Sending any of these, or a different folder, visibility or externalId, from the browser fails with 400 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 client.uploadTokens.sign({ uploadPresetId, externalId, expiresIn }). Signing happens locally with your API key and makes no request to CalmLens.

The call returns the token and its expiry time, in milliseconds since the Unix epoch.

const { token, expiresAt } = await client.uploadTokens.sign({
  uploadPresetId: "preset_4Lk8Qw2Xm9Rt5Vb3Nc7P",
  externalId: "post-42",
  expiresIn: 600,
});

Each token:

  • uploads one asset. A second upload with it fails with 409 upload-token/used; an upload that fails frees the token for a retry.
  • can start its upload until it expires, 10 minutes after signing by default (set expiresIn, up to 1 hour). Once the upload has started, the token stays valid for its 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, and for a preset with public visibility also to share them (assets:share). Revoking the key stops its tokens working.

Uploading from a browser

Only the JavaScript SDK runs in browsers and apps. Its CalmLensAppClient, from calmlens/app, uploads through an upload preset instead of an API key. Install calmlens and let your bundler resolve the import below; on a plain HTML page without a bundler, add an import map  that points calmlens/app at a copy of the SDK's module that you host.

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

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

This client has only client.assets.create(), client.assets.classify(), client.assets.uploadPart() and client.assets.retrieve({ assetId }), for its own uploads. They return the asset's id, name, uploadPresetId and createdAt, its upload.status and upload.partsReceived, and its classification.status and classification.failureReason, plus classification.moderation.status when the preset shows decisions. An upload is settled once classification.status is completed or failed. 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>:

RequestEndpoint
Upload a file or start a multipart uploadPOST /upload-presets/:uploadPresetId/assets
Upload a file's raw bytesPOST /upload-presets/:uploadPresetId/assets
Upload the next partPOST /upload-presets/:uploadPresetId/assets/:assetId/part
Check an uploadGET /upload-presets/:uploadPresetId/assets/:assetId

Uploading from your server through a preset

Pass the preset's ID as uploadPresetId 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 and metadata. Processing options you send replace the preset's as a whole rather than merging with them, so include every option you need; leave them out to use the preset's. A visibility that differs from the preset's, or a folder that differs from the one the preset sets, fails with 400 upload-preset/field-not-allowed.

Errors

CodeMeaning
404 upload-preset/not-foundNo preset with this ID in the project.
403 upload-preset/disabledThe preset is paused.
401 upload-preset/token-requiredThe preset requires an upload token and none was sent.
415 upload/unsupported-typeThe preset doesn't accept this file type (details.source is preset).
413 upload/too-largeThe file is larger than the preset allows (details.source is preset, and details.limitBytes is its limit).
429 upload-preset/daily-limit-reachedThis client reached the preset's daily limit. Retry-After says when the next UTC day starts.
403 upload-preset/origin-not-allowedThe site isn't in the preset's allowed sites.
400 upload-preset/field-not-allowedThe upload set a field the preset or token controls.
401 upload-token/invalidThe token is malformed, for another preset, or signed by a key that can't upload here.
401 upload-token/expiredThe token expired before the upload started.
409 upload-token/usedThe token already uploaded an asset.

Last updated

Signing in

Signing out

Cookies on CalmLens

We use essential cookies for sign-in and security. With your permission, functional cookies remember your preferences and Google Analytics measures website use and signups. Optional ad measurement cookies link Google ad clicks to signups. Personalised advertising stays off. Manage cookies