Images & Icons
Endpoints for serving and managing an Assistant's icon, and for generating imagery with AI.
Every mutating route on this page is AI-gated. The permission.assistant.write
check used in their pre-blocks requires the caller to hold AI access, so a
tenant without AI enabled cannot upload, generate, or delete Assistant icons.
Most of these endpoints stream binary data or call a live image-generation
provider, so only the deterministic JSON responses are captured below.
GET /api/assistants/{id}/icon
Serve the Assistant's stored icon.
Authentication: Permissive stack (basic / token / session / session JWT /
tenant), so a guest page's credential-less <img> fetches can resolve the icon.
Pre-blocks: assistant.lookupForIcon(params.id)
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
height | integer | Re-encode the icon to PNG at this height (1-1024) |
width | integer | Re-encode the icon to PNG at this width (1-1024) |
Response:
When an icon File is stored, the route streams the image bytes with an
appropriate Content-Type header (binary, not shown). When height or width
is supplied, the image is re-encoded to PNG via sharp before streaming.
When no icon is stored, the pre-block answers 404 with a JSON body.
{
"statusCode": 404,
"error": "Not Found",
"message": "No icon found"
}
PUT /api/assistants/{id}/icon
Set the Assistant's icon from a prior upload.
Authentication: Required (AI access)
Pre-blocks: permission.assistant.write
Request Body:
This route takes an upload handle, not a raw multipart file body. The upload
value is an upload id returned by the upload service.
| Field | Type | Required | Description |
|---|---|---|---|
upload | string | Yes | Upload id from a prior upload session |
progress | string | No | Progress identifier for upload tracking |
Response:
Responds 201 Created with the stored icon File and a Location header
pointing at the icon. This route ingests upload bytes against the live upload
service, so it is not captured here.
DELETE /api/assistants/{id}/icon
Remove the Assistant's icon and revert to the default.
Authentication: Required (AI access)
Pre-blocks: permission.assistant.write
Response:
Responds 200 with an empty body (Informer convention), not 204. The handler
removes the Assistant's File rows; deleting when no icon is set is still a 200
no-op.
GET /api/assistants/{id}/favicon.ico
Serve the Assistant's icon as a favicon.
Authentication: Permissive stack (same as the icon route)
Pre-blocks: assistant.lookupForIcon(params.id)
Response:
The icon bytes converted to ICO (sharp then toIco) with an appropriate
Content-Type header (binary, not shown).
POST /api/_create-image
Generate an image with AI. This route is not Assistant-specific.
Authentication: Required (AI access)
Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).
Request Body:
There is no model field; the size defaults to 256x256.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Image description |
size | string | No | Image dimensions (default 256x256) |
progress | string | No | Progress identifier for tracking |
Example Request:
{
"prompt": "A professional icon representing sales analytics",
"size": "512x512"
}
Response:
The route calls server.ai.generateImage against a live provider, so it is not
captured here.
POST /api/assistants/{id}/_create-image
Generate an image with AI and set it as the Assistant's icon.
Authentication: Required (AI access)
Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).
Pre-blocks: permission.assistant.write
Request Body:
This route takes only a prompt. There is no size or model field.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Image description |
Example Request:
{
"prompt": "A professional icon representing sales analytics"
}
Response:
Responds 201 Created with the generated icon File and a Location header. The
handler generates the image, replaces the Assistant's icon File, and returns the
new File. Because it calls server.ai.generateImage against a live provider, it
is not captured here.
GET /api/assistants/{id}/files/{fileId}/embeddings/{embeddingId}/image
Serve an image extracted from a file embedding.
Authentication: Required
Response:
The extracted image bytes with an appropriate Content-Type header (binary, not
shown).