> ## 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.

# Files

> Upload and manage organization files with the Erdo API and CLI.

The file store gives each uploaded or downloaded file its own identity in the selected organization. A file has a `file:<id>` handle, filename, detected media type, size, SHA-256 hash, source, access level and metadata.

Files are organization-visible by default. A private file is readable only by its creator and organization admins. The file service checks access on every read, signed URL, list result and delete. Deletion requires the creator or an organization admin.

Images uploaded in chat, screenshots, generated media and files produced by code also appear in the file store. These files inherit access from the thread, run or resource that produced them; outputs without a parent stay private to their creator. Producing tools return a `file_handle` alongside their existing image, dataset or download reference. Use that handle with `read_file`, attachment tools or code inputs.

Screenshots and generated images include dimensions and media type in their metadata. Existing image links and `view_screenshot` continue to work. Outputs over the 100 MiB file limit keep their existing delivery and include a note explaining why no file handle was added.

## Extend a rendering to a new aspect ratio

Ask your agent to extend a rendering to another aspect ratio, for example 4:3 to 16:9 for a wide carousel slot. Only an image recorded as a rendering (`image_kind` set to `rendering` on the Knowledge attachment) can be extended. A real photograph is refused, because generating new content around it would misrepresent the property; the agent crops it to the slot instead. An image with no recorded kind is refused until you record what it is. The agent keeps your rendering unchanged and generates only the new margins, between 1:3 and 3:1. The result is saved as a new file captioned "Artist's conception, digitally extended" and marked as a rendering, so pages that use it carry the rendering disclosure. Your original is never overwritten, and the credits match an image edit.

## Inbound email attachments

Attachments received by an inbox or sending domain are retained as files, up to 100 MiB each. Inbox attachments keep the inbox's access; sending-domain reply attachments are available to the organization. Inbox and received-email reads return filename, media type, size, status and a `file:<id>` handle once storage completes. Pending, failed and skipped attachments show their status; failures and skipped files include a reason. Mail receipt still succeeds when an attachment cannot be stored.

These files have source `email`. Erdo stores their bytes without executing or rendering them. They stay linked to the received message, and file deletion is refused while that link remains.

## CLI

```bash theme={null}
erdo files upload ./brand-guide.pdf --source-ref brand-guide-v1
erdo files upload ./brand-guide.pdf ./logo.png ./assets
erdo files upload ./assets --recursive
erdo files upload --url https://example.com/brand-guide.pdf
erdo files list --media-type application/pdf --limit 50
erdo files get <file-id>
erdo files delete <file-id>
```

The selected organization comes from the active CLI account or `--org`. Local uploads are limited to 100 MiB. The CLI sends files above 16 MiB straight to storage through a signed URL, because the API gateway refuses request bodies over 32 MiB (and base64 adds a third), then records the file. `erdo files upload` accepts several paths and directories. A directory uploads its direct children; add `--recursive` to include subdirectories. Hidden files and `__MACOSX` folders are always skipped. Files upload one at a time and each prints a JSON line with `path`, `ok`, and either `id`, `handle`, `filename` and `byte_size` or an `error`. The command exits non-zero if any file fails, after attempting the rest. It never prints the signed upload or download URL; use `erdo files get` when you need a short-lived read URL. `--source-ref` names a single target, so it is only accepted with one file. URL downloads are performed by Erdo's server-side download path. The service infers their filename from the provider; `--filename` overrides it. Supply a stable `--source-ref` when retrying a write to the same target; a retry with the same organization, source reference and bytes returns the existing file. Files are not deduplicated across different targets.

To send files with a message, see [Message attachments](https://docs.erdo.ai/message-attachments.md).

## API

All endpoints use the authenticated organization. Identity and organization are never supplied in request bodies.

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/v1/files` | Upload base64 bytes or ask the server to download `source_url` |
| `POST` | `/v1/files/uploads` | Begin a direct upload for a file above roughly 20 MiB: returns `upload_id`, a signed `upload_url` and its `content_type` |
| `POST` | `/v1/files/uploads/:id/complete` | Record the file after you `PUT` the raw bytes (with that `Content-Type`) to `upload_url`; repeat the `filename` and optional `source`, `source_ref`, `access` and `metadata` |
| `GET` | `/v1/files` | List files with pagination and optional `source`, `media_type` and filename `query` filters |
| `GET` | `/v1/files/:id` | Return metadata and a short-lived signed URL |
| `DELETE` | `/v1/files/:id` | Delete the file and its bytes |

JSON/base64 and URL uploads are limited to 100 MiB decoded, but a JSON request body above 32 MiB (about 24 MiB of file) is refused by the gateway with HTTP 413, so send larger files through the direct upload pair. The signed URL lasts one hour and accepts one `PUT`; `complete` refuses a missing or over-100 MiB object. Resumable tus uploads are planned for a later phase. Each file owns its bytes. Without a source reference, a byte upload creates a new file even when the bytes match an existing file. URL uploads default the retry reference to the source URL and optional supplied filename.

Supported CSV, TSV, Excel, JSON, JSONL and Parquet files derive queryable datasets. PDF, DOCX, PPTX, TXT, Markdown, HTML, XML and YAML files derive document datasets; document text is extracted when `read_file` is called. `GET /v1/files/:id`, `erdo files get`, and `read_file` show each derivation's state, attempts, result reference, waiting reason, and failure reason. Queued derivations may wait when the organization reaches its active or daily quota; their status explains the wait.

## MCP and agents

The MCP tools are `erdo_upload_file`, `erdo_begin_file_upload`, `erdo_complete_file_upload`, `erdo_list_files`, `erdo_get_file`, and `erdo_delete_file` in the `files` toolset. They use the same access rules and limits as the API.

Agents with attachment tools can use `list_files`, `read_file`, and `write_file`. Save new contents with `write_file` using a filename and exactly one of `text` or `content_base64`. The tool returns a `file:<id>` handle; retrying the same tool call with the same bytes returns the original file. File access follows the authenticated run context. The existing upload API, MCP tool, and CLI command also create files. Text reads support byte ranges; document reads return extracted text when ready and clearly report queued, running, or failed derivation otherwise. Image reads show the image for that tool call. Use `get_attachment_details` or the sandbox's `content_slugs` with a `file:<id>` handle when code needs the original file.

Email, WhatsApp replies, and SMS/MMS sends accept an `attachments` array of `file:<id>` handles. Each send checks access again and applies its channel limits. Approval cards show attachment names, types and sizes. SMS attachments require a number and provider that support MMS.

Derived datasets reference the original file bytes. File deletion is refused while datasets, dataset revisions, Knowledge records, or retained send records still reference the file. The error identifies the links to remove first.

You can attach an organization file to a workspace Knowledge record. The record keeps a reference to the original file, so deleting that file remains blocked while the record uses it.

## Files in chat and on agents

Drop or pick any file type in the chat box: fonts (`.otf`, `.ttf`, `.woff2`), zip archives, video, audio or any other binary. Erdo stores the file in your organization's file store and attaches it to your message as a `file:<id>` handle, so the agent can read it, load it in code, or attach it to Knowledge (for example, a brand font or logo on a Brand Style record). The message shows the file's name and size and keeps them after you reload the thread.

CSV, Excel, PDF, Office and text files still become datasets or documents, and images still go through the image path. Stored files do not count toward the dataset limit. Chat uploads can be up to 50 MiB; a larger file is refused with its name, size and the limit.

Chat images keep their existing image upload limit and also register a file handle. Code-workspace files written under `output/` keep their download buttons and gain a file handle; each run stores its outputs separately.

On the Agents page, uploading a reference file that is not a document stores it the same way and adds agent-specific Knowledge that names the file's `file:<id>` handle, so that agent can use it in later conversations.


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