Icon URL Resolution#

Dify stores app and agent icons as file UUIDs (or emoji strings) in the database. When entities are serialized to API responses, image-type icons must be converted into time-limited signed URLs so clients can actually fetch them. This conversion happens at serialization time — usually inside Pydantic response models — via the build_icon_url helper and graphon.file.helpers.get_signed_file_url.

Key components#

build_icon_url logic: returns None if icon or icon_type is None, or if icon_type is not IconType.IMAGE (i.e., emoji icons are passed through unchanged) 1. The signed URL itself is generated by file_helpers.get_signed_file_url(icon), which uses the FILES_URL / FILES_ACCESS_TIMEOUT configuration (default 300 s) 2.

Where icon_url is added to responses#

Icon URL resolution is applied via Pydantic @computed_field so the resolved URL is automatically included in model_dump() output without any manual call-site wiring.

App responses (api/controllers/console/app/app.py) — all three main app response shapes carry icon_url:

• AppPartial.icon_url — app list items
• RecentAppResponse.icon_url — home-page "Continue Work" cards
• AppDetailWithSite.icon_url — full app detail / create / update responses
• AppDetailSiteResponse.icon_url — embedded site sub-object within app detail

Explore / recommended apps (api/controllers/console/explore/recommended_app.py):

• RecommendedAppInfoResponse.icon_url — uses @computed_field with build_icon_url

Site / web public responses (api/controllers/web/site.py):

• WebSiteResponse.icon_url is built by WebAppRuntimeQueryService.get_bootstrap() (in api/services/web_app_runtime_query_service.py) during the web app bootstrap phase. The service calls FileService.get_icon_url() to select the appropriate URL scheme: in Cloud deployments with S3 storage it uses get_file_presigned_url() for a direct S3 presigned URL; otherwise it uses file_helpers.get_signed_file_url().

Knowledge dataset related-apps (api/controllers/console/datasets/datasets.py):

• RelatedAppResponse.icon_url uses @model_validator(mode="after") instead of @computed_field: self.icon_url = self.icon_url or build_icon_url(self.icon_type, self.icon). This allows a pre-computed URL to be passed in and preserved.

Site model in shared fields (api/controllers/common/fields.py):

• Site.icon_url uses @computed_field but calls file_helpers.get_signed_file_url directly rather than going through build_icon_url.

Gap: AgentRosterResponse has no icon_url#

AgentRosterResponse (and the related AgentComposerAgentResponse) expose raw icon and icon_type fields but do not include an icon_url computed field. Consumers of the agent roster API receive only the raw UUID — they must resolve it themselves or accept that no signed URL is provided. This is inconsistent with all of the app-entity response types described above.

Configuration#

Signed URL expiry and base URL are governed by FileAccessConfig 2:

Quick-reference: patterns in use#