Imagelato API reference

Every endpoint of the Imagelato REST API, generated from the API itself.

All endpoints are relative to https://api.imagelato.com. Create an API key in your Imagelato dashboard, then authenticate every request with it.

apiKey — HTTP Basic auth carrying only the API key secret: Authorization: Basic base64(<key secret>).

accessToken — Operator session token issued by the Imagelato dashboard: Authorization: Token <access token>.

Download the OpenAPI specification for use with your own tooling.

Batches

GET/api/batches

List batches

Lists the processed image batches of your organization, optionally filtered by projectId. Requires the batches:read scope.

batches:readapiKeyaccessToken
Parameters
NameInTypeDescription
projectIdquerystring
limitqueryinteger
skipqueryinteger
sortFieldquerystring
sortDirectionquerystring (ASC | DESC)
Responses
StatusMeaning
200Array of batches
401Missing or invalid credentials
403API key is missing the batches:read scope
429API key rate limit exceeded
DELETE/api/batches

Delete a batch

Deletes a batch and every S3 object it produced. Identify it with either ?url=<encoded> or ?_id=<batchId>. Emits the batch.deleted webhook event. Requires the batches:write scope.

batches:writeapiKeyaccessToken
Parameters
NameInTypeDescription
_idquerystring
urlquerystring
Responses
StatusMeaning
200The deleted batch
401Missing or invalid credentials
403API key is missing the batches:write scope
404Not found (or not owned by your organization)
429API key rate limit exceeded
GET/api/batches/{batchId}

Get a batch by id

Fetches a single processed image batch by id, scoped to your organization. Requires the batches:read scope. Returns 404 when the batch belongs to another organization, so ids cannot be probed.

batches:readapiKeyaccessToken
Parameters
NameInTypeDescription
batchIdrequiredpathstring
Responses
StatusMeaning
200The batch
401Missing or invalid credentials
403API key is missing the batches:read scope
404Not found (or not owned by your organization)
429API key rate limit exceeded

Images

POST/api/images/temporary

Store a screenshot for 30 days

PNG data URL up to 4 MiB. Writes one lifecycle-managed object without permanent batches, variants or webhooks. S3 expiration is asynchronous.

apiKeyaccessToken
Request body
FieldTypeDescription
filerequiredstring
Responses
StatusMeaning
200Temporary image URL (no batch created)
400Invalid PNG
401Missing credentials
403Missing images write scope
429Rate limit exceeded
GET/api/images

List uploaded images

Lists your organization's image keys (derived from its processed batches), optionally filtered by prefix. Requires the images:read scope.

images:readapiKeyaccessToken
Parameters
NameInTypeDescription
prefixquerystring
Responses
StatusMeaning
200Array of image object keys
401Missing or invalid credentials
403API key is missing the images:read scope
429API key rate limit exceeded
POST/api/images

Process an image

Uploads a base64 image and resizes/reformats it to the requested sizes and formats (or those of a named template), returning a batch of CDN URLs. Emits the batch.created webhook event. Requires the images:write scope.

images:writeapiKeyaccessToken
Request body
FieldTypeDescription
filerequiredstringData URI, e.g. data:image/png;base64,<...>
projectIdstring
slugstring
templatestring
formatsarray
sizesarray
Responses
StatusMeaning
200The created batch (main URL + variants)
401Missing or invalid credentials
403API key is missing the images:write scope
429API key rate limit exceeded

Projects

GET/api/projects

List projects

Lists the projects of your organization. Requires the projects:read scope.

projects:readapiKeyaccessToken
Responses
StatusMeaning
200Array of projects
401Missing or invalid credentials
403API key is missing the projects:read scope
429API key rate limit exceeded
POST/api/projects

Create a project

Creates a project in your organization. Emits the project.created webhook event. Requires the projects:write scope.

projects:writeapiKeyaccessToken
Request body
FieldTypeDescription
namerequiredstring
vanityIdstringOptional lowercase route id derived from name
Responses
StatusMeaning
200The created project
401Missing or invalid credentials
403API key is missing the projects:write scope
429API key rate limit exceeded
PUT/api/projects/{projectId}

Update a project

Updates an owned project while preserving display-name case.

Parameters
NameInTypeDescription
projectIdrequiredpathstring
Request body
FieldTypeDescription
namerequiredstring
vanityIdstring
Responses
StatusMeaning
200The updated project
GET/api/projects/{projectId}

Get a project by id

Fetches a single project by id, scoped to your organization. Requires the projects:read scope. Returns 404 when the project belongs to another organization, so ids cannot be probed.

projects:readapiKeyaccessToken
Parameters
NameInTypeDescription
projectIdrequiredpathstring
Responses
StatusMeaning
200The project
404Not found (or not owned by your organization)

Templates

GET/api/templates

List templates

Lists the templates of your organization, optionally filtered by projectId. Requires the templates:read scope.

templates:readapiKeyaccessToken
Parameters
NameInTypeDescription
projectIdquerystring
fieldsquerystringComma-separated projection of fields to return
Responses
StatusMeaning
200Array of templates
401Missing or invalid credentials
403API key is missing the templates:read scope
429API key rate limit exceeded
POST/api/templates

Create or update a template

Creates a template (or updates one when _id is supplied) in your organization. Emits template.created or template.updated. Requires the templates:write scope.

templates:writeapiKeyaccessToken
Request body
FieldTypeDescription
namerequiredstring
projectIdrequiredstring
formatsarray
sizesarray
Responses
StatusMeaning
200The created or updated template
401Missing or invalid credentials
403API key is missing the templates:write scope
429API key rate limit exceeded
GET/api/templates/{idOrName}

Get a template by id or name

Fetches a single template by id (uuid) or by name, scoped to your organization. Requires the templates:read scope. Returns 404 when the template belongs to another organization, so ids cannot be probed.

templates:readapiKeyaccessToken
Parameters
NameInTypeDescription
idOrNamerequiredpathstring
Responses
StatusMeaning
200The template
404Not found (or not owned by your organization)

Webhook subscriptions

GET/api/webhooksubscriptions

List webhook subscriptions

Webhook subscriptions deliver batch.created, batch.deleted, project.created, template.created and template.updated events to your server as signed POST requests (X-Imagelato-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the secret is only returned once, on create.

accessToken
Responses
StatusMeaning
200Array of webhook subscriptions (without secrets)
POST/api/webhooksubscriptions

Create a webhook subscription

The response includes the signing secret exactly once — store it; it cannot be retrieved again.

accessToken
Request body
FieldTypeDescription
projectIdrequiredstring
urlrequiredstring
eventsarray (batch.created | batch.deleted | project.created | template.created | template.updated)Empty array subscribes to all events
Responses
StatusMeaning
200The created subscription, including its secret
PUT/api/webhooksubscriptions/{webhookSubscriptionId}

Update a webhook subscription

url, events and active are editable; the secret and project are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200The updated subscription (without secret)
DELETE/api/webhooksubscriptions/{webhookSubscriptionId}

Delete a webhook subscription

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200Deleted