CLI
Use the object’s UUID fromerdo 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
SendPOST /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:
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 includesasset_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:
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.
