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:

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.