Managing Assets (File Attachments)

How to create, upload files to, view, and organize assets in Metapad.

Assets let you attach files (images, PDFs, documents) to your model as first-class elements. They appear in the Model Navigator alongside nodes and can be organized in folders.

What Are Assets?

An asset is a model element that can hold a file. Think of it as a named container for a document or image within your model.

• Assets live in the Assets section of the Model Navigator
• Each asset holds one file (or none — the file is optional). In a multilingual model an asset can also hold one file per language, so an English screenshot and its German counterpart share a single asset
• Assets have a label, description, and tags, just like nodes
• Assets can be organized in folders

Creating an Asset

1. In the Model Navigator, find the Assets section
2. Click the + button to create a new asset
3. Give it a descriptive name (e.g., "Architecture Diagram", "Requirements Spec")

Uploading a File

1. Select the asset in the Model Navigator
2. In the Properties Panel, find the File section
3. Click Upload File
4. Choose a file from your computer
5. The file is uploaded and attached to the asset
6. File metadata (name, type, size) appears in the Properties Panel

Viewing and Downloading

1. Select an asset with a file attached
2. In the Properties Panel, click View Asset to open/download the file
3. The file opens in a new browser tab

Removing a File

1. Select the asset
2. In the Properties Panel, click Remove File
3. The file is detached — the asset element remains in the model

Organizing Assets

• Folders: Drag assets into folders in the Model Navigator, just like nodes
• Tags: Add tags to assets for categorization and filtering
• Rename: Edit the asset label in the Properties Panel

Assets and the API

You can work with assets from outside the app too — useful when files are produced by a build, a report generator, or a script.

• Uploading a file from your machine — use the REST API's Upload Asset endpoint. It takes the file directly, creates the asset and attaches the file in one request. Up to 100 MB.
• Replacing a file, or adding another language — post to Attach Asset File with the asset's id. The asset keeps its id, so links to it stay valid, and ?locale=de adds a German file alongside the English one instead of replacing it. This is how a script can keep a screenshot up to date in both languages.
• Uploading a file that already has a URL — an AI assistant or MCP client can call create_asset and then upload_asset_file, pointing Metapad at a public link. This route fetches the file server-side, so it can't reach a file that only exists on your computer.
• Reading what's in a file — get_asset_content returns a PDF as extracted text, a text or CSV file as-is, and an image as something the AI can actually look at. This is how you ask the assistant a question about a requirements document you've attached.
• Finding assets — use list_assets. Assets are kept separately from nodes, so a normal node search won't return them.

See API Tokens and External Access for how to get a token, and the MCP API Reference and REST API Reference for the details.

Tips

• Assets are model elements — they persist in the model and are included in exports
• Use meaningful names so team members can find assets easily
• Organize related assets in folders (e.g., "Design Documents", "Screenshots")
• Other collaborators can see assets in real-time