Skip to main content

Images & Icons

Endpoints for managing assistant icons and generating images.

Assistant Icons​

GET /api/assistants/{id}/icon​

Get the current icon for an assistant.

Response: Icon image (PNG/SVG)

PUT /api/assistants/{id}/icon​

Upload a custom icon for an assistant.

Permission: assistant:write

Content-Type: multipart/form-data

Request Body: Icon image file

Response: Updated assistant object

DELETE /api/assistants/{id}/icon​

Remove custom icon (revert to default).

Permission: assistant:write

Response: 204 No Content

GET /api/assistants/{id}/favicon.ico​

Get the assistant's icon as a favicon.

Response: Favicon ICO file

Image Generation​

POST /api/_create-image​

Generate an image using AI (not assistant-specific).

Authentication: Required (AI seat)

Request Body:

FieldTypeRequiredDescription
promptstringYesImage description
modelstringNoImage generation model
sizestringNoImage dimensions

Example Request:

{
  "prompt": "A professional icon representing sales analytics",
  "size": "512x512"
}

Response:

{
  "url": "https://cdn.example.com/generated-image.png",
  "prompt": "A professional icon representing sales analytics",
  "model": "dall-e-3",
  "size": "512x512",
  "createdAt": "2024-02-09T10:00:00Z"
}

POST /api/assistants/{id}/_create-image​

Generate an image specifically for an assistant.

Authentication: Required (AI seat)

Permission: assistant:write

Request Body: Same as POST /api/_create-image

Response: Image metadata with URL

Use Cases:

  • Generate custom assistant icons
  • Create branded imagery for assistant UIs
  • Produce visual aids for instructions

Icon Management Best Practices​

Icon Formats​

  • Preferred: SVG (scalable, small file size)
  • Supported: PNG, JPG, GIF
  • Recommended Size: 512x512 pixels minimum

Icon Guidelines​

  • Use simple, recognizable symbols
  • Ensure good contrast for dark/light themes
  • Keep file size under 100KB
  • Use transparent backgrounds when possible

Default Icons​

If no custom icon is set, the system uses the icon field value (string identifier) to render a default icon from the icon library.