Skip to main content
Upload a file, register it for the place it will appear, then reference it from a listing field, guide, or offer.

​
Scopes

Every upload has a scope. Use the same scope to create the upload URL and to register the upload. Every method requires Portals access for the workspace and a token with write access. These MCP tools use the platform access tier and are available to Operator.

​
Upload media

  1. Call Create Portal Upload URL with the scope. Add listing_id for listing_field.
  2. Send a POST request to data.upload_url with the raw file bytes and the file’s Content-Type header.
  3. Read storageId from the upload response.
  4. Call Register Portal Upload with that ID as storage_id and the same scope.
  5. Use the registered media:
    • listing_field: set storageId on an image or video node to data.storage_id when updating the field.
    • guide: use data.url as cover_image_url, a media item’s imageUrl, or a video embed’s url with uploaded: true.
    • offer: use data.url as image_url.
Images support JPEG, PNG, WebP, GIF, and AVIF up to 10 MiB. Videos support MP4 and WebM up to 50 MiB. Upload URLs expire after one hour. Complete registration before the URL expires. Registration checks the stored media type and size. Each operation checks current workspace access and permissions. Media registered for another workspace or scope is rejected.

​
MCP tools

create_portal_listing_upload_url and register_portal_listing_upload remain available as aliases for the listing_field scope.