Images Reference

Endpoints for the tenant image library. For the guide-level walk-through, see Attachments and Images.

Base path: /v3/images/ Public proxy: /i/{image_id} (no auth)

GET /v3/images#

List images.

Query parameters:

Parameter	Notes
`folder`	Filter by folder name
`search`	Substring match on filename or alt text
`page`	1-indexed (default 1)
`page_size`	1–100 (default 25)

Response (200):

json
{
  "result": [
    {
      "id": "img_01HXYZ",
      "filename": "logo.png",
      "original_filename": "company-logo.png",
      "content_type": "image/png",
      "size": 42195,
      "width": 600,
      "height": 200,
      "url": "https://scaisend.scailabs.ai/i/img_01HXYZ",
      "thumbnail_url": "https://scaisend.scailabs.ai/i/img_01HXYZ?variant=thumbnail",
      "alt_text": "Acme logo",
      "folder": "brand",
      "created_at": "2026-04-23T10:00:00Z",
      "updated_at": "2026-04-23T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 25
}

POST /v3/images#

Upload an image.

Content-Type: multipart/form-data.

Form fields:

Field	Type	Required	Notes
`file`	binary	Yes	JPEG, PNG, GIF, or WebP; ≤ 10 MB
`alt_text`	string	No	Accessibility alt text
`folder`	string	No	Organize images into folders

Response (201): ImageResponse (same shape as list items).

Errors:

Status	Cause
400	Unsupported MIME type or malformed image
413	File exceeds 10 MB

GET /v3/images/folders#

List distinct folder names in use.

Response (200):

json
{"folders": ["brand", "marketing-q2", "headshots"]}

GET /v3/images/{image_id}#

Get image metadata.

Response (200): ImageResponse.

Errors: 404 if not found.

PATCH /v3/images/{image_id}#

Update metadata.

Request body:

Field	Type	Notes
`alt_text`	string
`folder`	string

Response (200): updated ImageResponse.

DELETE /v3/images/{image_id}#

Delete an image. Messages already sent that referenced this image are unaffected — they've either embedded the bytes (CID mode) or the proxy URL will return 410 Gone going forward.

Response (204): no body.

GET /i/{image_id}#

Public image proxy. No authentication.

Headers on response:

Header	Value
`Content-Type`	Original MIME type (`image/png`, etc.)
`Content-Length`	Byte size
`Cache-Control`	`public, max-age=31536000, immutable`
`ETag`	Content hash for conditional requests

Query parameters:

Parameter	Notes
`variant`	`thumbnail` (returns a smaller version for preview UI)

HEAD /i/{image_id}#

Same headers, no body. Useful for link-checking and preflight.

Size limits#

Limit	Value
Max file size	10 MB
Supported formats	JPEG, PNG, GIF, WebP

Images exceeding these limits are rejected at upload time with 413.

Attachments and Images
Tracking — image_embed_mode: proxy uses these URLs.