Skip to main content

Tutorial: Manage tags

Read and update spatial annotations on your iGUIDE floor plans using the Portal API's tag endpoints.

Time to complete: ~10 minutes

What you'll learn:

  • How to read existing tags on an iGUIDE
  • How to update tag content, colors and styles
  • How to embed rich content with Markdown and iframes
  • Which tag fields are editable vs read-only

Prerequisites​

Before you begin, you need:

  • App ID and Access Token (see Your First iGUIDE for setup)
  • A published iGUIDE with at least one tag

What are tags?​

Tags are interactive hotspot annotations placed on an iGUIDE's floor plan. They appear as clickable markers in the 3D tour and can display titles, descriptions, images and embedded content. Tags are typically created through the iGUIDE Portal editor or during the drafting process.

The Portal API lets you manage tag content—title, description, color, style—but not tag placement. Position, floor association and panorama visibility are set through the Portal editor and are read-only via the API.

Step 1: Set up your environment​

Store your credentials and iGUIDE ID as environment variables:

export APP_ID="your-app-id-here"
export APP_TOKEN="your-access-token-here"
export IGUIDE_ID="igABC123"

Step 2: Read existing tags​

Fetch all tags for an iGUIDE with a GET request:

curl "https://manage.youriguide.com/api/v1/iguides/$IGUIDE_ID/tags" \
  -H "Accept: application/json" \
  -H "X-Plntr-App-Id: $APP_ID" \
  -H "X-Plntr-App-Token: $APP_TOKEN"

Response:

[
  {
    "id": 1,
    "globalId": "0e0fe74b-55dd-5892-9102-cba5995add3f",
    "title": "Kitchen",
    "content": "Renovated in 2023 with quartz countertops and stainless steel appliances.",
    "color": "blue",
    "design": 0,
    "opacity": 100,
    "pos": [275.79, 2052.62, 1050.25],
    "floorId": 1,
    "initialPanoId": 1,
    "allPanoIds": [1, 2],
    "visiblePanoIds": [1, 2]
  },
  {
    "id": 2,
    "globalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Primary bedroom",
    "content": "Spacious room with walk-in closet and ensuite bathroom.",
    "color": "green",
    "design": 1,
    "opacity": 100,
    "pos": [180.50, 1800.30, 1050.25],
    "floorId": 1,
    "initialPanoId": 3,
    "allPanoIds": [3, 4],
    "visiblePanoIds": [3]
  }
]

Each tag includes both editable content fields and read-only positioning data. See Tag field reference below for the full breakdown.

Step 3: Update tag content​

To update existing iGUIDE tags, send a PUT request with an array of tag objects. Include the id (or globalId) to identify which tag to update, along with the fields you want to change.

You only need to include the tags you're updating—any tags missing from the request remain unchanged.

curl -X PUT "https://manage.youriguide.com/api/v1/iguides/$IGUIDE_ID/tags" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Plntr-App-Id: $APP_ID" \
  -H "X-Plntr-App-Token: $APP_TOKEN" \
  -d '[
    {
      "id": 1,
      "title": "Gourmet kitchen",
      "content": "Fully renovated in 2023. Features quartz countertops, stainless steel appliances and a walk-in pantry."
    }
  ]'

Response:

The response contains the full tag list for the iGUIDE, including any updates you made:

[
  {
    "id": 1,
    "globalId": "0e0fe74b-55dd-5892-9102-cba5995add3f",
    "title": "Gourmet kitchen",
    "content": "Fully renovated in 2023. Features quartz countertops, stainless steel appliances and a walk-in pantry.",
    "color": "blue",
    "design": 0,
    "opacity": 100,
    "pos": [275.79, 2052.62, 1050.25],
    "floorId": 1,
    "initialPanoId": 1,
    "allPanoIds": [1, 2],
    "visiblePanoIds": [1, 2]
  },
  {
    "id": 2,
    "globalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Primary bedroom",
    "content": "Spacious room with walk-in closet and ensuite bathroom.",
    "color": "green",
    "design": 1,
    "opacity": 100
  }
]
note

Tags you don't include in the request are not modified. Unknown tag IDs are silently discarded.

warning

The update tag endpoint only lets you modify existing tags in your iGUIDE. You cannot add new tags with this endpoint.

Step 4: Customize tag appearance​

You can change how tags look in the Viewer by updating color, design and opacity.

Colors​

Set color to a predefined name or a custom hex RGB value:

[
  { "id": 1, "color": "red" },
  { "id": 2, "color": "#A8341B" }
]

Predefined colors:

ValueColor
"blue"Blue (#0388CC)
"green"Green (#50CF62)
"red"Red (#F65B55)
"orange"Orange (#F7A345)
"yellow"Yellow (#F7CE4A)
"purple"Purple (#B270D3)

Hotspot design​

The design field controls the hotspot style. Accepted values are 0 (transparent) or 1 (opaque).

[{ "id": 1, "design": 1 }]

Opacity​

Control hotspot visibility with opacity (0–100). Setting opacity to 0 makes the hotspot invisible until the user hovers over it—useful for subtle annotations that don't clutter the tour.

[{ "id": 1, "opacity": 60 }]

Step 5: Embed rich content​

Markdown​

The content field supports CommonMark Markdown—text formatting, lists, tables, images and links all work.

[
  {
    "id": 1,
    "title": "Kitchen upgrades",
    "content": "## Recent renovations\n\n- Quartz countertops\n- Stainless steel appliances\n- Hardwood flooring\n\n[View full specs](https://example.com/specs)"
  }
]

iGUIDE asset references​

You can embed images (or link to files) from the iGUIDE's uploaded assets using the assets:/// protocol in Markdown:

[
  {
    "id": 1,
    "content": "Check out this detail: ![close-up photo](assets:///detail-photo.jpg)\n\nDownload the [inspection report](assets:///report.pdf)."
  }
]
tip

Upload assets to the iGUIDE first using the asset upload endpoints, then reference them in tag content with assets:///FILENAME.

Iframe embeds​

Set the iframe field to embed external content (videos, virtual staging, 3D models) directly in the tag popup. When iframe is set, the content field is ignored.

[
  {
    "id": 1,
    "title": "Virtual staging",
    "iframe": "https://example.com/virtual-staging/kitchen"
  }
]
Iframe overrides content

When iframe is set, the tag popup displays the iframe instead of the content Markdown. To switch back to Markdown content, update the tag with an empty iframe value.

Tag field reference​

FieldTypeEditableDescription
idintegerNoTag ID within the iGUIDE. Use this to identify tags in update requests.
globalIdstringNoImmutable UUID. Persistent across re-drafts. Can also be used to identify tags in updates.
titlestringYesTitle displayed on the tag hotspot. Max 1,000 characters.
contentstringYesBody text in CommonMark Markdown. Max 10,000 characters. Ignored when iframe is set.
colorstringYesPredefined color name or hex RGB (e.g. "#A8341B").
designintegerYesHotspot style: 0 (default) or 1 (alternate).
opacitynumberYesHotspot opacity: 0 (invisible until hover) to 100 (fully visible).
iframestringYesURL displayed in an iframe inside the tag popup. Overrides content. Max 1,000 characters.
posarrayNo3D coordinates [x, y, z] on the floor plan. Set via the Portal editor.
floorIdintegerNoFloor the tag is placed on.
initialPanoIdintegerNoEntry panorama for viewing the tag.
allPanoIdsarrayNoAll panorama IDs the tag is associated with.
visiblePanoIdsarrayNoPanoramas where the tag hotspot is visible.
tip

Use id or globalId to identify tags in update requests. If both are present, globalId takes priority for matching.

Next steps​