{ "openapi": "3.0.0", "info": { "title": "Imagelato API", "version": "1.0.0" }, "servers": [ { "url": "https://api.imagelato.com" } ], "components": { "schemas": { "Entity": { "type": "object", "description": "An Imagelato resource.", "additionalProperties": true }, "Error": { "type": "object", "required": [ "name", "message", "status" ], "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "basic", "description": "HTTP Basic auth carrying only the API key secret: Authorization: Basic base64()." }, "accessToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Operator session token issued by the Imagelato dashboard: Authorization: Token ." } } }, "paths": { "/api/batches": { "get": { "tags": [ "Batches" ], "summary": "List batches", "description": "Lists the processed image batches of your organization, optionally filtered by `projectId`. Requires the `batches:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "projectId", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "sortField", "schema": { "type": "string", "example": "lastEditTime" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Array of batches", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `batches:read` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiBatches" }, "delete": { "tags": [ "Batches" ], "summary": "Delete a batch", "description": "Deletes a batch and every S3 object it produced. Identify it with either `?url=` or `?_id=`. Emits the `batch.deleted` webhook event. Requires the `batches:write` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "_id", "schema": { "type": "string" } }, { "in": "query", "name": "url", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `batches:write` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not owned by your organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteApiBatches" } }, "/api/batches/{batchId}": { "get": { "tags": [ "Batches" ], "summary": "Get a batch by id", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "batchId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `batches:read` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not owned by your organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiBatchesByBatchId" } }, "/api/images/temporary": { "post": { "tags": [ "Images" ], "operationId": "uploadTemporaryImage", "summary": "Store a screenshot for 30 days", "description": "PNG data URL up to 4 MiB. Writes one lifecycle-managed object without permanent batches, variants or webhooks. S3 expiration is asynchronous.", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string" } } } } } }, "responses": { "200": { "description": "Temporary image URL (no batch created)", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "retentionDays" ], "properties": { "url": { "type": "string", "format": "uri" }, "retentionDays": { "type": "integer", "enum": [ 30 ] } } } } } }, "400": { "description": "Invalid PNG", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing images write scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/images": { "get": { "tags": [ "Images" ], "summary": "List uploaded images", "description": "Lists your organization's image keys (derived from its processed batches), optionally filtered by `prefix`. Requires the `images:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "prefix", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of image object keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `images:read` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiImages" }, "post": { "tags": [ "Images" ], "summary": "Process an image", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "description": "Data URI, e.g. `data:image/png;base64,<...>`" }, "projectId": { "type": "string" }, "slug": { "type": "string" }, "template": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" } }, "sizes": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "The created batch (main URL + variants)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `images:write` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postApiImages" } }, "/api/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects", "description": "Lists the projects of your organization. Requires the `projects:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "responses": { "200": { "description": "Array of projects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `projects:read` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiProjects" }, "post": { "tags": [ "Projects" ], "summary": "Create a project", "description": "Creates a project in your organization. Emits the `project.created` webhook event. Requires the `projects:write` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "vanityId": { "type": "string", "description": "Optional lowercase route id derived from name" } } } } } }, "responses": { "200": { "description": "The created project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `projects:write` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postApiProjects" } }, "/api/projects/{projectId}": { "put": { "tags": [ "Projects" ], "summary": "Update a project", "description": "Updates an owned project while preserving display-name case.", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "vanityId": { "type": "string" } } } } } }, "responses": { "200": { "description": "The updated project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "putApiProjectsByProjectId" }, "get": { "tags": [ "Projects" ], "summary": "Get a project by id", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found (or not owned by your organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiProjectsByProjectId" } }, "/api/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "description": "Lists the templates of your organization, optionally filtered by `projectId`. Requires the `templates:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "projectId", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `templates:read` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiTemplates" }, "post": { "tags": [ "Templates" ], "summary": "Create or update a template", "description": "Creates a template (or updates one when `_id` is supplied) in your organization. Emits `template.created` or `template.updated`. Requires the `templates:write` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "projectId" ], "properties": { "name": { "type": "string" }, "projectId": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" } }, "sizes": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The created or updated template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the `templates:write` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until the request may be retried.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postApiTemplates" } }, "/api/templates/{idOrName}": { "get": { "tags": [ "Templates" ], "summary": "Get a template by id or name", "description": "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.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "idOrName", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "404": { "description": "Not found (or not owned by your organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiTemplatesByIdOrName" } }, "/api/webhooksubscriptions": { "get": { "tags": [ "Webhook subscriptions" ], "summary": "List webhook subscriptions", "description": "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=,v1=`). 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.\n", "security": [ { "accessToken": [] } ], "responses": { "200": { "description": "Array of webhook subscriptions (without secrets)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } } } } }, "operationId": "getApiWebhooksubscriptions" }, "post": { "tags": [ "Webhook subscriptions" ], "summary": "Create a webhook subscription", "description": "The response includes the signing `secret` exactly once — store it; it cannot be retrieved again.\n", "security": [ { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "projectId", "url" ], "properties": { "projectId": { "type": "string" }, "url": { "type": "string", "example": "https://example.com/imagelato-webhook" }, "events": { "type": "array", "description": "Empty array subscribes to all events", "items": { "type": "string", "enum": [ "batch.created", "batch.deleted", "project.created", "template.created", "template.updated" ] } } } } } } }, "responses": { "200": { "description": "The created subscription, including its secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "postApiWebhooksubscriptions" } }, "/api/webhooksubscriptions/{webhookSubscriptionId}": { "put": { "tags": [ "Webhook subscriptions" ], "summary": "Update a webhook subscription", "description": "`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.\n", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated subscription (without secret)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "putApiWebhooksubscriptionsByWebhookSubscriptionId" }, "delete": { "tags": [ "Webhook subscriptions" ], "summary": "Delete a webhook subscription", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } } }, "operationId": "deleteApiWebhooksubscriptionsByWebhookSubscriptionId" } } }, "tags": [] }