> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Knowledge attachments

> Upload images and files to a Knowledge record from the CLI, REST API or MCP.

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`:

```bash theme={null}
erdo knowledge attach <objectId> ./acme-logo.svg \
  --caption "Acme partner logo" --role customer-logo --org acme

erdo knowledge attach <objectId> --url https://example.com/acme-logo.png \
  --caption "Acme partner logo" --org acme

# Supply a filename when the download URL doesn't contain one.
erdo knowledge attach <objectId> acme-logo.png \
  --url https://example.com/download --org acme
```

`--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`:

```json theme={null}
{
  "filename": "acme-logo.svg",
  "source_url": "https://example.com/acme-logo.svg",
  "caption": "Acme partner logo",
  "role": "customer-logo"
}
```

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](https://docs.erdo.ai/shared-files.md). 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:

```jsx theme={null}
<ErdoImage assetId="<asset_id>" alt="Acme partner logo" />
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.