> ## 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 Listing Fields

> Edit structured listing fields with formatted text, images, and videos.

Portal listing fields contain guest information such as directions, parking instructions, house rules, and Wi-Fi details.
These methods change portal overrides. They do not change the source data in your property management system (PMS).

## Access

Every method requires Portals access for the workspace.
Without that access, REST returns `403` and MCP returns `forbidden` with the message `Portals are not enabled for this workspace.`
Operations access alone does not authorize these methods.

Reading requires `AccessProperties`. Editing, creating upload URLs, and registering uploads require `ManageProperties` and a token with write access.
These MCP tools use the `platform` access tier and are available to Operator.

Use the PMS `listingId` returned by `list_listings` as `listing_id`.
The ID must identify one property in the workspace. Ambiguous IDs are rejected.
For supported subunit fields, supply `subunit_id` when reading or editing.

## Read, set, and reset

[Get Portal Listing Fields](/api-reference/portals/listing-fields/get) returns each field's effective value, PMS value, source, local override mode, and rich document.
The response also includes URLs for media used in the documents.

[Update Portal Listing Field](/api-reference/portals/listing-fields/update) changes one field.
For `action: "set"`, supply exactly one of `value` or `document`.
The supplied value or document replaces the complete field content. Other fields remain unchanged.

```json theme={null}
{
  "action": "set",
  "value": "Park in the garage beside the entrance."
}
```

For `action: "reset"`, omit `value` and `document`.
Reset removes the override and restores the PMS value.
For a subunit, reset restores the inherited property value.

```json theme={null}
{
  "action": "reset"
}
```

## Formatted content

Fields with `supports_rich_content: true` accept structured rich documents.
The format supports bold text, italic text, links, headings, lists, variables, images, and videos.
Send the structured document directly. HTML and Markdown strings are plain text values.
Include text or a caption with media.
Keep existing media nodes when replacing a document if you want to retain those images or videos.

```json theme={null}
{
  "action": "set",
  "document": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Use the garage entrance.",
            "marks": [{ "type": "bold" }]
          }
        ]
      },
      {
        "type": "image",
        "attrs": {
          "storageId": "<registered_storage_id>",
          "caption": "Garage entrance"
        }
      }
    ]
  }
}
```

## Upload media

1. Call [Create Portal Listing Upload URL](/api-reference/portals/listing-fields/create-upload-url) for the workspace and listing.
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 Listing Upload](/api-reference/portals/listing-fields/register-upload) with that ID as `storage_id` for the same workspace and listing.
5. Use the registered ID in an image or video node when updating the field.

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

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 listing is rejected.

## MCP tools

| Tool | Purpose |
| - | - |
| `get_portal_listing_fields` | Read the current fields and media. |
| `update_portal_listing_field` | Set or reset one field. |
| `create_portal_listing_upload_url` | Create a single-use upload URL. |
| `register_portal_listing_upload` | Register an uploaded file for a listing. |


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