# Photos and videos

Search `list_media` first. It returns IDs, filenames, types, byte counts and hashes, with pagination. Use an existing asset ID when the intended file is already present.

## Upload through MCP or JSON API

`upload_media` takes `revision`, `name`, `mimeType` and `base64`. Send raw base64 without a data-URL prefix. The decoded file must be between 12 bytes and 2 MiB. Supported formats: JPG, PNG, GIF, WebP, MP4 and WebM. The service checks file signatures; renaming a file or changing its MIME label does not convert it.

The response contains `assetId`, `revision` and `reused`. Identical bytes already in the site are reused. If the response is lost, resend the same bytes; do not make a new copy just to obtain a response.

## Multipart API for larger files

Files up to 3 MiB can use multipart upload:

```bash
curl --fail-with-body https://api.history-showcase.com/api/platform/agent/v1/media \
  -H "Authorization: Bearer $HISTORYSHOWCASE_TOKEN" \
  -F 'revision=REVISION_FROM_CONTEXT' \
  -F 'file=@school-photo.jpg;type=image/jpeg'
```

The `content` scope and current editing permission are required. The response returns the new revision and asset ID. Multipart uploads use revision protection; if the response is lost, inspect `list_media` before resending with a new revision.

## Attach or use a photo

Use `mediaAssetIds` in a content change, or a supported image field such as `primaryLogo`, `backgroundImage` or `headshot` in a design change. Use this site's uploaded image ID; arbitrary image URLs and cross-site asset IDs are rejected.

Upload before making a batch that references the asset, then use the upload's returned revision. Uploads are independent operations; a failed content batch does not delete an uploaded asset.

## Limits and recovery

There are at most 3,000 uploaded assets per site. SVG, HTML and executable formats are not accepted. Large archival video ingestion is a separate operator workflow, not an agent capability. Resize or compress files locally when they exceed the upload limit. Do not claim a file is attached until you have verified its ID in the saved entry or design.