The CalmLens REST API lets your server upload content for moderation, read decisions, organize assets and create CDN links. Each reference page lists its endpoints, describes the objects they return, and gives every endpoint a card with parameters, request and response schemas, error codes and code samples. For walkthroughs, start with the Quick start or a guide.
Base URLs
Service
Base URL
REST API
https://api.calmlens.com/v1
CDN
https://cdn.calmlens.com/v1
Request and response bodies are JSON unless an endpoint says otherwise, and timestamps are milliseconds since the Unix epoch. The full API is also available as an OpenAPI document.
Authentication
Authenticate every request, except the health check, with a project API key in the X-Api-Key header:
X-Api-Key: your-api-key
Keep API keys on your server. Do not expose them in browser code or public client bundles. Each key belongs to one project and grants only the permissions you choose when you create it; see Authentication. Browsers and other untrusted clients should load private assets through signed URLs.
Conventions
IDs. Resources are addressed by their UUIDs. Assets can also carry your own externalId, which the CDN accepts in place of the asset ID.
Pagination. List endpoints take a zero-based pageIndex and a pageSize from 1 to 100, and return items, total and hasMore. The events feed uses a cursor instead. See Pagination.
Filtering. The asset list accepts an RSQL-style filter. See Asset filters.
Errors. Failed requests return an HTTP error status with a JSON body of code, message and traceId. Handle errors by code; each endpoint card lists the codes it can return. See Error handling.
Request IDs. Every response carries an X-Request-Id header. Include it when you contact support about a request.
Idempotency. Upload and create requests accept an Idempotency-Key header, so a retry after a timeout returns the first response instead of creating a second asset. See Retrying requests safely.
Rate limits. CalmLens does not publish a general requests-per-second limit. Throttled requests return 429 with a Retry-After header. Upload allowances and file-size limits return their own upload/* errors.
SDKs. The JavaScript, PythonGo, Rust, Ruby and Java SDKs wrap these endpoints, handle authentication and uploads, and return typed errors.
Start a multipart upload by streaming the first part's raw bytes as the request body, with the X-CalmLens-Upload: part header and the file's Content-Type.
We use essential cookies to keep you signed in and the site secure. With your permission, we'll also use functional cookies to remember preferences such as your layout and documentation language, and to offer Google One Tap sign-in. We don't use analytics or advertising cookies. Manage cookies