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.
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.
Each upload preset has its own revision. Send revision: 0 to create a preset only if no preset has its key. A conflict is 409upload-preset/revision-conflict.
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.
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.
revision*number
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.
name*string
Display name
access*AccessEnum
Who can upload from a browser: token needs an upload token signed by your server, anyone accepts the preset ID alone
Allowed values
tokenanyone
enabled*boolean
Whether the preset accepts uploads
visibility*Visibility
Visibility of uploaded assets
Allowed values
publicprivate
revealDecision*boolean
Whether browser uploads see the moderation decision for their own upload
createdAt*number
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.
processingOptionsobject (optional)
Processing options for every upload through the preset, such as keeping content after moderation or reading text with OCR. Browser uploads can't change them.
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
projectId*string
ID of the project
revision*number
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.
settings*object
The metadata fields object
MetadataFields
projectId*string
ID of the project
revision*number
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.
fields[]*MetadataField[]
The project's metadata fields, in display order
Endpoint details
List Upload Presets
List a page of the project's upload presets, oldest first.
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.
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.
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.
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.
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.
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.
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.
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