Lenses
Use a project API key to create or update versioned lens definitions.
| Endpoint | Description |
|---|---|
PUT / | Create a lens or update it with a version greater than the current version |
PUT / | Create lenses or update them with their next versions |
The lens object
| Field | Type | Presence | Description |
|---|---|---|---|
id | string | Required | Unique lens ID |
projectId | string | Optional, nullable | ID of the project that owns the lens; null for built-in lenses |
userId | string | Optional, nullable | ID of the user whose account created the lens |
version | integer | Optional | Definition version. Updates must use a greater version; it is part of the CDN cache key. Default: 1. |
identifier | string | Required | Name used in CDN URLs after @. Lowercase letters, numbers and hyphens, at most 50 characters. |
name | string | Required | Display name |
description | string | Optional, nullable | Optional description of what the lens produces |
type | "image" | "video" | "audio" | "document" | "website" | Required | Asset type the lens applies to |
active | boolean | Required | Whether the CDN serves the lens |
transforms | object[] | Optional, nullable | Transforms applied in order to produce the derived asset |
transforms[].type | string | Required | Transform type, such as imageTransform |
transforms[].options | any | Required | Options for the transform type, such as width and format |
createdAt | integer | Required | When the lens was created, in milliseconds since the Unix epoch |
updatedAt | integer | Optional | When the lens was last updated, in milliseconds since the Unix epoch |
Endpoint details
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.ensureLens({
"identifier": "thumbnail",
"name": "Thumbnail",
"type": "image",
"active": true,
"version": 1,
"transforms": [
{
"type": "imageTransform",
"options": {
"fit": "scale-down",
"width": 640,
"format": "webp"
}
}
]
});
Response
lensobjectRequired
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
409
lens/version-conflictLens updates require a version greater than the current version.
import { CalmLensClient } from "@calmlens/sdk";
const client = new CalmLensClient({
apiKey: "your-api-key",
projectId: "your-project-id"
});
const response = await client.ensureLenses({
"lenses": [
{
"identifier": "thumbnail",
"name": "Thumbnail",
"type": "image",
"active": true,
"version": 1,
"transforms": [
{
"type": "imageTransform",
"options": {
"fit": "scale-down",
"width": 640,
"format": "webp"
}
}
]
}
]
});
Response
lenses[]object[]Required
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
409
lens/version-conflictLens updates require a version greater than the current version.