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:
| Access | How a browser uploads | Use it for |
|---|---|---|
Users your server approves (token) | With an upload token your server signed for that upload | Apps 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 client | Static 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
| Setting | Effect |
|---|---|
| File types | MIME types the preset accepts, such as image/* or video/mp4. Empty accepts every supported type. |
| Maximum file size | Largest file the preset accepts. Multipart uploads are checked as their parts arrive. |
| Folder | Folder that uploads go into. Browser uploads can't choose another one. |
| Moderation policy | Policy 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. |
| Visibility | Visibility of uploaded assets. |
| Keep content after moderation | Keeps 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 images | Runs OCR on uploaded images and moderates the text it finds as well. |
| Streaming Preview | Prepares an adaptive stream of uploaded audio and video. Needs content to be kept. |
| Show the decision to the uploader | When on, browser uploads see the moderation status of their own upload. Reports, metadata and URLs are never returned to the browser. |
| Daily upload limit | Most 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 sites | Origins 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 uploads | Turn 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>:
| Request | Endpoint |
|---|---|
| Upload a file or start a multipart upload | POST / |
| Upload a file's raw bytes | POST / |
| Upload the next part | POST / |
| Check an upload | GET / |
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
| Code | Meaning |
|---|---|
| 404 upload-preset/not-found | No preset with this ID in the project. |
| 403 upload-preset/disabled | The preset is paused. |
| 401 upload-preset/token-required | The preset requires an upload token and none was sent. |
| 415 upload/unsupported-type | The preset doesn't accept this file type (details.source is preset). |
| 413 upload/too-large | The file is larger than the preset allows (details.source is preset, and details.limitBytes is its limit). |
| 429 upload-preset/daily-limit-reached | This client reached the preset's daily limit. Retry-After says when the next UTC day starts. |
| 403 upload-preset/origin-not-allowed | The site isn't in the preset's allowed sites. |
| 400 upload-preset/field-not-allowed | The upload set a field the preset or token controls. |
| 401 upload-token/invalid | The token is malformed, for another preset, or signed by a key that can't upload here. |
| 401 upload-token/expired | The token expired before the upload started. |
| 409 upload-token/used | The token already uploaded an asset. |