Configuration API reference

Use a project API key to read and change the project's upload presets, settings and metadata fields. The same settings are in the portal, and a change made in either place shows in the other. The policies, lenses and hash lists have their own endpoints.

Guide: Manage configuration in code.

Revisions

Every object here has a revision. Send back the one you read, and a change made since is refused with 409, so concurrent deploys can't silently overwrite each other. A request that changes nothing keeps the revision, so you can send the same definition on every deploy.

Leave revision out to write whatever is stored.

Permissions

Reading needs upload-presets:read, settings:read or metadata:read, and changing needs the matching :write permission. The Configurator role holds all of them, without access to members or API keys. Naming a policy on an upload preset also needs policies:write.

Endpoints

EndpointDescription
GET /projects/:projectId/upload-presetsList a page of the project's upload presets, oldest first.
PUT /projects/:projectId/upload-presetsCreate each upload preset, or replace it with the definition sent, by key.
DELETE /upload-presets/:uploadPresetIdDelete an upload preset.
GET /projects/:projectId/settingsGet the project's settings, with every default filled in, and the revision to send back with a change.
PUT /projects/:projectId/settingsReplace the project's settings.
GET /projects/:projectId/metadata-fieldsList the project's metadata fields in display order, with the revision to send back with a change.
PUT /projects/:projectId/metadata-fieldsCreate each metadata field, or replace it with the definition sent, by ID.
DELETE /projects/:projectId/metadata-fields/:fieldIdDelete a metadata field definition.

The upload preset object

UploadPreset
idstring
Unique upload preset ID
projectIdstring
ID of the project that owns the preset
keystring
Key you choose for the preset, unique in its project: lowercase letters, numbers and hyphens, at most 64 characters. Configuration files and the ensure endpoint address presets by key.
revisionnumber
Counts changes to the preset, starting at 1. Send it back when you change the preset, so a change made since you read it isn't overwritten.
namestring
Display name
accessAccessEnum
Who can upload from a browser: token needs an upload token signed by your server, anyone accepts the preset ID alone
Allowed values
tokenanyone
enabledboolean
Whether the preset accepts uploads
visibilityVisibility
Visibility of uploaded assets
Allowed values
publicprivate
revealDecisionboolean
Whether browser uploads see the moderation decision for their own upload
createdAtnumber
When the preset was created, in milliseconds since the Unix epoch
createdByUserIdstring (optional)
ID of the user who created the preset
allowedContentTypes[]string[]
MIME types the preset accepts, such as image/*. Empty or null accepts any supported type.
maxSizeInBytesnumber (optional)
Largest upload the preset accepts, in bytes. null uses the standard upload limits.
folderIdstring (optional)
Folder that uploads go into
policyIdstring (optional)
Moderation policy for uploads through the preset, one of the organisation's policies. null uses the project's policy.
dailyUploadLimitnumber (optional)
Most uploads the preset accepts from each client (IP address) per UTC day, counted separately for every client. Required when access is anyone.
allowedOrigins[]string[]
Sites allowed to upload from the browser. Empty or null allows any site.
updatedAtnumber (optional)
When the preset was last updated, in milliseconds since the Unix epoch

The project settings object

ProjectSettings
projectIdstring
ID of the project
revisionnumber
Counts changes to the project's settings and metadata fields, starting at 1. Send it back with a change, so a change made since you read it isn't overwritten.

The metadata fields object

MetadataFields
projectIdstring
ID of the project
revisionnumber
Counts changes to the project's settings and metadata fields, starting at 1. Send it back with a change, so a change made since you read it isn't overwritten.

Endpoint details

List Upload Presets

List a page of the project's upload presets, oldest first.

OpenAPI YAML
GET
https://api.calmlens.com/v1/projects/
/upload-presets
const response = await client.uploadPresets.list({
  "sort": "createdAt"
});

Query Parameters

Edit any value to update the generated request examples.

string (optional)
The previous page’s nextCursor; omit for the first page
number (optional)
Items per page, 1 to 100 (default 50)
string (optional)
Sort order: a comma-separated list of fields from createdAt, id, each ascending unless prefixed with -. The default is createdAt. An id tie-breaker in the first field's direction is added.

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
404project/not-found
Project not found
400cursor/invalid
The cursor is invalid or belongs to a different query.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Ensure Upload Presets

Create each upload preset, or replace it with the definition sent, by key. Fields left out take their defaults. An unchanged preset is returned as it is, with the same revision, so deploys can send their presets every time. Every preset is checked before any is saved.

OpenAPI YAML
PUT
https://api.calmlens.com/v1/projects/
/upload-presets
const response = await client.uploadPresets.ensure({
  "uploadPresets": [
    {
      "key": "profile-photos",
      "revision": 2,
      "name": "Profile photos",
      "access": "token",
      "allowedContentTypes": [
        "image/*"
      ],
      "visibility": "public",
      "revealDecision": true,
      "allowedOrigins": [
        "https://example.com"
      ]
    }
  ]
});

Request Body

Edit any value to update the generated request examples.


Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
415request/unsupported-content-type
Send the request body as application/json.
404project/not-found
Project not found
409upload-preset/revision-conflict
The upload preset changed, or was created or deleted, since you read it. Retrieve it again and retry with its current revision.
400upload-preset/daily-limit-required
A preset that anyone can upload to needs a daily upload limit.
400upload-preset/invalid-folder
The folder isn't in this project. Choose a folder from this project and try again.
400upload-preset/invalid-policy
The policy isn't one of this organisation's. Choose one of its policies and try again.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Delete Upload Preset

Delete an upload preset. Browsers can no longer upload through it; assets already uploaded stay.

OpenAPI YAML
DELETE
https://api.calmlens.com/v1/upload-presets/
const response = await client.uploadPresets.delete({
  "uploadPresetId": "preset_4Lk8Qw2Xm9Rt5Vb3Nc7P"
});

Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
404upload-preset/not-found
Upload preset not found. Check the preset ID in the portal.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Get Project Settings

Get the project's settings, with every default filled in, and the revision to send back with a change.

OpenAPI YAML
GET
https://api.calmlens.com/v1/projects/
/settings
const response = await client.projectSettings.get();

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
404project/not-found
Project not found
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Update Project Settings

Replace the project's settings. Settings left out return to their defaults. Unchanged settings keep their revision. The project's policy and metadata fields have their own endpoints.

OpenAPI YAML
PUT
https://api.calmlens.com/v1/projects/
/settings
const response = await client.projectSettings.update({
  "revision": 4,
  "settings": {
    "optOutJurisdictions": [
      "EU"
    ],
    "blockUnmoderatedAssets": true
  }
});

Request Body

Edit any value to update the generated request examples.

number (optional)
The revision you last read. Settings or metadata fields changed since are refused with project-settings/revision-conflict. Omit it to replace them whatever their revision.
number (optional)
Needed when turning on aiMediaSearchEnabled: the most indexing units you accept for the project's existing media. A smaller value than the estimate is refused with search/estimate-changed, whose details give the estimate.

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
415request/unsupported-content-type
Send the request body as application/json.
404project/not-found
Project not found
409project-settings/revision-conflict
The project's settings or metadata fields changed since you read them. Retrieve them again and retry with the current revision.
409search/estimate-changed
Turning on AI media search needs a searchIndexingBudgetUnits of at least the current indexing estimate, which details.indexingUnits gives.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

List Metadata Fields

List the project's metadata fields in display order, with the revision to send back with a change.

OpenAPI YAML
GET
https://api.calmlens.com/v1/projects/
/metadata-fields
const response = await client.metadataFields.list();

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
404project/not-found
Project not found
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Ensure Metadata Fields

Create each metadata field, or replace it with the definition sent, by ID. Other fields are kept, and new ones are added at the end. Unchanged fields keep their revision.

OpenAPI YAML
PUT
https://api.calmlens.com/v1/projects/
/metadata-fields
const response = await client.metadataFields.ensure({
  "revision": 4,
  "fields": [
    {
      "id": "userId",
      "title": "User",
      "type": "string",
      "icon": "user",
      "color": "#2563eb"
    }
  ]
});

Request Body

Edit any value to update the generated request examples.

number (optional)
The revision you last read. Settings or metadata fields changed since are refused with project-settings/revision-conflict. Omit it to replace them whatever their revision.

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
415request/unsupported-content-type
Send the request body as application/json.
404project/not-found
Project not found
409project-settings/revision-conflict
The project's settings or metadata fields changed since you read them. Retrieve them again and retry with the current revision.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

Delete Metadata Field

Delete a metadata field definition. Assets keep the metadata values they hold.

OpenAPI YAML
DELETE
https://api.calmlens.com/v1/projects/
/metadata-fields/
const response = await client.metadataFields.delete({
  "fieldId": "example"
});

Query Parameters

Edit any value to update the generated request examples.

number (optional)
The revision you last read. Fields changed since are refused with project-settings/revision-conflict.

Response


Error Codes

401api-key/missing
Authentication required. Send your project API key in the X-Api-Key header.
401api-key/invalid
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403api-key/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
403auth/permission-denied
This API key lacks a permission the request needs (details.permission names it, such as assets:download for an asset's folder, and details.role the least role that includes it), or the resource belongs to another project.
400validation/invalid-request
The request's parameters, query or body are invalid. details.issues lists each problem, with its path and issue code.
404project/not-found
Project not found
404metadata-field/not-found
The project has no metadata field with this ID.
409project-settings/revision-conflict
The project's settings or metadata fields changed since you read them. Retrieve them again and retry with the current revision.
500server/internal-error
An internal error occurred. Retry later, and quote requestId to support.

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