🖼️ Image Upload

Upload an image and get back a hosted URL. Backed by Backblaze B2 object storage.

Upload an Image

curl -X POST https://www.agent-utils.com/api/upload \

-H "x-api-key: au_your_key" \

-F "file=@screenshot.png" \

-F "retentionHours=24"

Response (201):

{

"success": true,

"data": {

"id": "9f3c1b2a-...",

"url": "https://www.agent-utils.com/api/file-host/9f3c1b2a-...",

"filename": "screenshot.png",

"contentType": "image/png",

"size": 184320,

"expiresAt": "2026-06-20T12:00:00.000Z"

}

Parameters

Field	In	Type	Description
file	form	binary	Required. The image file (jpeg, png, webp, or gif). Max 10 MB.
retentionHours	form	number	Optional. Hours until the file expires (default 24). Must be positive.
x-api-key	header	string	Required. Your AgentUtils API key.

Accessing a File

The returned url is publicly accessible — no API key required. It serves the image with the original content type and is cacheable. Files past their expiresAt return a 404.

curl https://www.agent-utils.com/api/file-host/{id}

Errors

Status	Cause
400	Missing `file` field or invalid `retentionHours`.
401	Missing or invalid API key.
413	File exceeds 10 MB.
415	Unsupported content type.
500	Storage backend error.