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

# Portal Uploads

> Upload images and videos for portal listing fields, guides, and offers.

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.

| Scope | Where it appears | Media | Permission |
| - | - | - | - |
| `listing_field` | Image and video nodes in a [listing field](https://docs.conduit.ai/api-reference/portals/listing-fields/overview.md) document. Requires `listing_id`. | Images and videos | `Manage Properties` |
| `guide` | [Guide](https://docs.conduit.ai/api-reference/portals/guides/overview.md) covers and blocks. | Images and videos | `Manage Portals` |
| `offer` | [Offer](https://docs.conduit.ai/api-reference/portals/offers/overview.md) images. | Images only | `Manage Portals` |

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](https://docs.conduit.ai/api-reference/portals/uploads/create-upload-url.md) 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](https://docs.conduit.ai/api-reference/portals/uploads/register-upload.md) 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`.

```json theme={null}
{
  "scope": "guide"
}
```

```bash theme={null}
curl --request POST "$UPLOAD_URL" \
  --header 'Content-Type: image/jpeg' \
  --data-binary @lobby.jpg
```

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

| Tool | Purpose |
| - | - |
| `create_portal_upload_url` | Create a single-use upload URL. |
| `register_portal_upload` | Register an uploaded file for its scope. |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.