Skip to main content
Attach files to an existing Knowledge object, such as your organization’s Brand Style record. Attachments use the same storage, access checks and image processing as files added in the app or captured by an agent. The app’s attachment picker accepts any file, including TTF, OTF, WOFF, WOFF2 and TTC fonts, ZIP archives and unknown binary formats. Files stay in their original format; archives are never extracted. Unknown binaries and ZIPs are available through private signed download URLs and cannot be served as public page assets.

CLI

Use the object’s UUID from erdo knowledge get or erdo knowledge list:
--caption describes the file and makes images searchable. The existing --description option does the same job; use one of them. --media-type supplies a MIME type hint, such as image/png. The server checks image bytes and refuses unsupported image types. --role adds a filename prefix: acme-logo.svg with --role customer-logo becomes customer-logo-acme-logo.svg. An existing prefix is preserved. Roles are lowercase letters, digits and hyphens, up to 80 characters. They use the existing filename convention; they are not a separate metadata classification. For an exact canonical name such as logo-primary.svg, supply that filename directly and omit --role. Commands use the active organization, or the organization selected by --org. The caller must have edit access to the object in that organization’s workspace. Scoped keys need resources:write to upload and resources:read to read back.

REST and MCP

Send POST /v1/knowledge/<objectId>/attachments, or call the erdo_attach_knowledge_asset MCP tool with object_id. Provide exactly one of content_base64 and source_url:
For bytes, send standard base64 in content_base64, with filename and a media_type such as image/svg+xml. media_type is optional when the service can detect it. caption and description are equivalent; conflicting values are refused. Organization and caller identity come from authentication and organization selection, never the JSON body. Base64 uploads are limited to 20 MiB decoded so the request fits the HTTP body limit. URL downloads accept up to 50 MiB for non-video files and 100 MiB for MP4 video. Downloads require HTTP(S), refuse URL credentials and block private network addresses, including redirect targets. Unsupported or mismatched URL content and HTML preview/login pages are refused. Unknown binary content is stored privately. Public SharePoint/OneDrive, Dropbox and Google Drive file links use the same download path, retaining sharing keys and guest cookies through redirects. Supply a filename when the share URL has none. Folder links require Import shared files. Dropbox folders use its hosted browser fallback; attaching a folder URL directly returns an explanation instead of saving the folder’s HTML preview or a ZIP of its contents.

Read back and embed

The response includes asset_id, object_id, filename, media_type, byte_size and public_url. Raster images also include width and height when the service can decode their dimensions. Dimensions can be absent for SVGs and other files. public_url is a root-relative path such as /public/knowledge-assets/<asset_id>. It is empty for file types the public asset endpoint doesn’t serve, such as PDFs; use their signed download URL. Uploading to a private record does not make an attachment public. A new attachment’s public URL returns 404 until it is published: an image or MP4 is published with its Knowledge record while the record is public and approved, and any servable file is published when a page embedding it is published or when you make that one attachment public. With either of the last two, the parent record can stay private. Turning an attachment’s own public access off does not withdraw what a public record publishes; make the record Workspace or move the attachment to another record. On an Erdo page, use the returned ID:
Use the returned public_url for a plain image URL. The caller supplies page alt text; the stored caption describes the attachment for readers and search. Website widgets can find images and MP4 videos in their own organization when the record is public and approved, or when you made that attachment public on its own — either by marking it public, or by publishing a page that embeds it. Either way the widget can show that media while its record stays private, using the attachment’s caption; it does not receive the private record’s title or body. PDFs, fonts and other non-media files never appear in widget media search. Neither do other files that happen to share public access without having been exposed in their own right: they still load from their URL, they just are not searchable. Removing an attachment’s public access removes it from new search results unless its record still publishes it. Read attachments with erdo knowledge get <objectId> or erdo knowledge assets list <objectId>. REST also offers GET /v1/knowledge/<objectId>/attachments; MCP offers erdo_list_knowledge_assets. These return signed download URLs and public visibility: public is the attachment’s own public access, and published_with_record means it loads publicly because its record is public and approved. Treat incomplete: true as a transient signing or visibility lookup failure before making a decision based on missing files. Re-uploading identical bytes under the same final filename to the same object returns the existing attachment. Different bytes produce another attachment; an upload does not replace a file already embedded on a page.