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

# Media & Image Hosting

> Upload images, video, audio, and documents to Marble's built-in media library and CDN, then embed them in posts or access them via the REST API and MCP.

Marble handles your media so you can focus on writing. Upload files to your
workspace, keep useful metadata with them, and serve them through Marble's CDN.

## Supported media types

<CardGroup cols={2}>
  <Card title="Images" icon="image">
    Upload common image formats including JPEG, PNG, GIF, AVIF, and WebP.
    Images include dimensions when Marble can read them.
  </Card>

  <Card title="Videos" icon="video">
    Host video files such as MP4 and WebM for posts, pages, and custom
    frontends.
  </Card>

  <Card title="Audio" icon="audio-lines">
    Store audio files such as MP3, WAV, OGG, and AAC for use in custom
    experiences.
  </Card>

  <Card title="Documents" icon="file-text">
    Upload documents such as PDFs and plain text files when you need CDN-backed
    downloads.
  </Card>
</CardGroup>

## How it works

When you upload media to Marble, the file is stored in Marble's object storage
and served from a CDN URL.

* **Fast delivery** — Media is served from `cdn.marblecms.com`
* **Stable URLs** — Use the returned URL in posts, websites, apps, or feeds
* **Metadata included** — Marble stores fields like name, alt text, MIME type,
  size, media type, dimensions, duration, blur hash, and upload date when
  available

## Using media in your posts

<Steps>
  <Step title="Open the Media Library">
    In the Marble dashboard, click on **Media** in the sidebar to access your
    media library.
  </Step>

  <Step title="Upload Files">
    Click **Upload** to add images, videos, audio, or documents. Files are
    available as soon as the upload finishes.
  </Step>

  <Step title="Insert into Posts">
    When editing a post, use the image or video controls to insert media from
    your library. You can also paste CDN URLs directly.
  </Step>
</Steps>

## Accessing media via API

You can read and manage media through the public API.

| Endpoint                | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `GET /v1/media`         | List media assets in your workspace.                                  |
| `GET /v1/media/:id`     | Get one media asset and its metadata.                                 |
| `POST /v1/media/upload` | Upload a small file directly. Requires a private API key.             |
| `PATCH /v1/media/:id`   | Update media metadata. Requires a private API key.                    |
| `DELETE /v1/media/:id`  | Delete a media asset and its stored file. Requires a private API key. |

Uploads through the API are intended for small files. For larger uploads, use
the dashboard uploader.

<Tip>
  As a rule of thumb, avoid using very large images in your posts. Users with
  slower internet connections will experience longer load times, which can hurt
  engagement.
</Tip>

## Managing your media

From the Media Library, you can:

* **Search and filter** — Find files quickly by name or media type
* **Edit metadata** — Keep names and alt text useful for humans and frontends
* **Delete unused files** — Remove media you no longer need
* **View file details** — See URL, file size, MIME type, dimensions, and upload
  date

## Using media with MCP

Marble's MCP server includes media tools for AI agents. Agents can list media,
inspect a single asset, update metadata, delete assets, and upload media from a
public URL.

<Note>
  Remote MCP servers cannot read files from your local filesystem directly. To
  upload through MCP, provide a URL that the server can fetch.
</Note>

<Note>
  Deleting media removes the stored file. Any post, website, app, or feed that
  uses that URL will stop loading it, so update those references before deleting
  an asset.
</Note>