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",
    "iconId": "light",
    "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",
    "iconId": "bathroom",
    "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",
    "iconId": "light",
    "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",
    "iconId": "bathroom",
    "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, iconId 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:

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

Icon

The iconId field selects which built-in icon the hotspot displays. Set it to the id of one of the available icons—for example "light", "thermostat", "fire_extinguisher", "photo" or "bathroom".

[{ "id": 1, "iconId": "thermostat" }]

For an up-to-date list of icons, see the Tag Icons page or fetch them from the GET /tags/icons endpoint.

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: Set a tag icon

The iconId field controls which built-in icon a tag hotspot displays. Valid values are the icon IDs listed on the Tag Icons page; for an up-to-date list you can also fetch them from the GET /tags/icons endpoint.

List the available icons

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

Response:

The icons array lists the available icons in display order. Each entry's id is a valid iconId value.

{
  "icons": [
    { "id": "light" },
    { "id": "thermostat" },
    { "id": "fire_extinguisher" },
    { "id": "photo" },
    { "id": "bathroom" }
  ]
}

Set or change a tag's icon

Update the tag with the chosen iconId:

[{ "id": 1, "iconId": "thermostat" }]

To change a tag's icon later, send another update with a different iconId.

note

See the Tag Icons page or the GET /tags/icons endpoint for an up-to-date list of icons.

Step 6: 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

Field	Type	Editable	Description
`id`	integer	No	Tag ID within the iGUIDE. Use this to identify tags in update requests.
`globalId`	string	No	Immutable UUID. Persistent across re-drafts. Can also be used to identify tags in updates.
`title`	string	Yes	Title displayed on the tag hotspot. Max 1,000 characters.
`content`	string	Yes	Body text in CommonMark Markdown. Max 10,000 characters. Ignored when `iframe` is set.
`color`	string	Yes	Predefined color name or hex RGB (e.g. `"#A8341B"`).
`iconId`	string	Yes	Built-in icon to display. Must be one of the IDs on the Tag Icons page or returned by `GET /tags/icons`.
`opacity`	number	Yes	Hotspot opacity: `0` (invisible until hover) to `100` (fully visible).
`iframe`	string	Yes	URL displayed in an iframe inside the tag popup. Overrides `content`. Max 1,000 characters.
`pos`	array	No	3D coordinates `[x, y, z]` on the floor plan. Set via the Portal editor.
`floorId`	integer	No	Floor the tag is placed on.
`initialPanoId`	integer	No	Entry panorama for viewing the tag.
`allPanoIds`	array	No	All panorama IDs the tag is associated with.
`visiblePanoIds`	array	No	Panoramas 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

Upload photos and assets — Upload images to reference in tag content with assets:///
Download deliverables — Download floor plans and media files from your iGUIDE
Listen for webhooks — Get notified when iGUIDEs are ready

Prerequisites​

What are tags?​

Step 1: Set up your environment​

Step 2: Read existing tags​

Step 3: Update tag content​

Step 4: Customize tag appearance​

Colors​

Icon​

Opacity​

Step 5: Set a tag icon​

List the available icons​

Set or change a tag's icon​

Step 6: Embed rich content​

Markdown​

iGUIDE asset references​

Iframe embeds​

Tag field reference​

Next steps​

Related resources​

Prerequisites

What are tags?

Step 1: Set up your environment

Step 2: Read existing tags

Step 3: Update tag content

Step 4: Customize tag appearance

Colors

Icon

Opacity

Step 5: Set a tag icon

List the available icons

Set or change a tag's icon

Step 6: Embed rich content

Markdown

iGUIDE asset references

Iframe embeds

Tag field reference

Next steps

Related resources