This is a library of ready-to-use sample GraphQL queries and mutations for Matterport’s Model API.

Each query and mutation contains a link to try the query in our interactive console. If you are logged into your account at my.matterport.com, you will be able to use the interactive console. If you have a Developer Tools license, the Interactive Console will be able to query all models in your account. If you are in Sandbox mode, it will only be able to query the demo model in your account.

With all queries, be sure to edit the variables, when provided, and insert a valid Model ID and valid data for all variables.

If you would like an application to build collections of API queries for testing and generating code to use in your applications, we recommend using Postman and have these snippets available in a sample collection.

Helpful Resources

Testing in Sandbox Mode

API Users in Sandbox mode can test these queries on a demo model in their account. The models() query will only return your demo model. Purchasing a developer license will change this behavior to show the models in your account. You can still find the SID of the demo model in production mode using the provided ‘Search for demo models in your account’ query found below.

Models Queries

models() queries get data from our models search engine. Searchable data can be found here.

Search for your models
query {
  models(query: "*") {
    totalResults
    results {
      id
      name
      description
    }
  }
}

Sample Response:

{
  "data": {
    "models": {
      "totalResults": 1,
      "results": [
        {
          "id": "MODEL_ID",
          "name": "352 E Java Dr",
          "description": ""
        }
      ]
    }
  }
}

Try this query in our interactive console

Search for demo models in your account

All accounts come with a demo model. This can be queried in sandbox mode for testing purposes. If you wish to find the demo models with a models query, use “demo: true” as your query. You can also include ‘demo’ in your results to verify that this is a demo model.

query {
  models(query: "demo:true", include: demo) {
    results {
      name
      demo
      id
    }
    nextOffset
    totalResults
  }
}

Sample Response:

{
  "data": {
    "models": {
      "results": [
        {
          "name": "Get Started",
          "demo": true,
          "id": "xiyHP9VkT1U"
        },
        {
          "name": "Get Started",
          "demo": true,
          "id": "YGYWqVqWDpm"
        }
      ],
      "totalResults": 2
    }
  }
}

Try this query in our interactive console

Search for archived models
query archivedModels {
  models(query: "state:inactive", include: inactive) {
    results {
      name
      state
      id
    }
    nextOffset
    totalResults
  }
}

Try this query in our interactive console

Search for Models with x # of Floors
query {
  models(query: "floors.count: 20") {
    results {
      id
      name
    }
    nextOffset
    totalResults
  }
}

Try this query in our interactive console

Model Queries

model() queries get data from individual models.

Get all Sweep Locations and Panoramic Images

Panoramic images are currently only available as skyboxes.

A skybox is made out of six images - each image individually projected onto the shape of a cube - that is: top, bottom, left, right, front and back sides. Skyboxes are available in 512x512 (resolution: low), 1024x1024 (resolution: high) and 2048 x 2048 (resolution: 2k) resolutions and come bundled with position and rotation data. 4096 x 4096 skyboxes are available for business and Enterprise customers who have purchased the ‘Advanced Imagery Bundle’ add-on.

fragment panoFragment on PanoramicImageLocation{
  id
  skybox(resolution: "2k") {
    id
    status
    format
    children
  }
}

query getSweeps($modelId: ID!){
    model(id: $modelId) {
      locations {
        id
        model { id }
        position { x, y, z }
        floor { id }
        room { id }
        panos { ...panoFragment }
    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "locations": [{
          "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
          "model": {
            "id": "MODEL_ID"
          },
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "panos": [{
            "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
            "skybox": {
              "id": "a0723324-ab3e-4500-bdee-8fec13d3ae9d",
              "status": "available",
              "format": "skybox",
              "children": [
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox0.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox1.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox2.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox3.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox4.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1",
                "https://qa-cdn-1.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/pan/~/high/a0723324ab3e4500bdee8fec13d3ae9d_skybox5.jpg?t=2-c81c9af53e390d7c5d9946f73a74665f0e06757c-1573701898-1"
              ]
            }
          }]
        }, ...
      }]
  }
}

Try this query in our interactive console

Get all Tags and Tag Data

Users can get all Tags from a model. Presently, attachments are not queryable.

Tags were previous called ‘mattertags’ and Model API continues to use this naming convention.

query getTags($modelId: ID!) {
  model(id: $modelId) {
    mattertags(includeDisabled: true) {
      id
      floor { id }
      created
      modified
      enabled
      color
      label
      description
      icon  # New!
      keywords
      media
      mediaType
      position { x, y, z }
      anchorPosition { x, y, z }
      discPosition { x, y, z }
      stemNormal { x, y, z }
      stemLength
      stemEnabled
      stemDirection { x, y, z } # Deprecated, use stemNormal and stemLength
    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "mattertags": [{
        "id": "ayi201wkujs",
        "floor": {
          "id": "pd0i1c4yq9w0y2zsb07ed23sb"
        },
        "created": "2017-09-29T19:45:57Z",
        "modified": "2019-11-18T22:26:42Z",
        "enabled": true,
        "color": "#03687d",
        "label": "Nest Thermostat",
        "description": "",
        "icon": "public_symbols_video",
        "keywords": [],
        "media": null,
        "mediaType": null,
        "position": {
          "x": 1.20415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "anchorPosition": {
          "x": 1.20415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "discPosition": {
          "x": 1.40415628,
          "y": -5.35434341,
          "z": 3.1942153
        },
        "stemNormal": {
          "x": 1,
          "y": 0,
          "z": 0
        },
        "stemLength": 0.2,
        "stemEnabled": true,
        "stemDirection": {
          "x": 0.2,
          "y": 0,
          "z": 0
        }
      }, ]
    }
  }
}

Try this query in our interactive console

Get all Dimensional Data from the Model, Floors and Rooms
query getDimensions($modelId: ID!) {
  model(id: $modelId) {
      name
      description
      dimensions {
      ...dimensions
      }
      floors {
      label
      dimensions(units: imperial) {
          ...dimensions
      }
    }
     rooms {
      id
      label
      tags
      dimensions {
          ...dimensions
      }
    }
  }
}

fragment dimensions on Dimension {
areaCeiling
areaFloor
areaFloorIndoor
areaWall
volume
depth
height
width
units
}

# variables

{
"modelId" : ""
}

Sample Response:

{
    "data": {
        "model": {
            "name": "Model Name",
            "description": "Model Description",
            "dimensions": {
                "areaFloor": 270.23811626434326,
                "areaFloorIndoor": 245.12091588974,
                "volume": 1185.8062753677368,
                "units": "metric"
            },
            "floors": [
                {
                    "label": "Floor 1",
                    "dimensions": {
                        "areaFloor": 1811.2674341550348,
                        "areaFloorIndoor": 1763.751272911024,
                        "areaWall": 4200.7835074106215,
                        "volume": 30221.99651317749,
                        "units": "imperial"
                    }
                },
                {
                    "label": "Floor 2",
                    "dimensions": {
                        "areaFloor": 1097.5486255027295,
                        "areaFloorIndoor": 874.7057536345482,
                        "areaWall": 2896.4391288173674,
                        "volume": 11654.396359551525,
                        "units": "imperial"
                    }
                }
            ],
            "rooms": [
                {
                    "id": "h26t7ky77ew74yb0pg8qqf5rd",
                    "label": "6",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 12.459799766540527,
                        "areaFloorIndoor": 12.459799766540527,
                        "areaWall": 41.87590026855469,
                        "volume": 37.56352996826172,
                        "height": 3.0147781372070312,
                        "units": "metric"
                    }
                },
                {
                    "id": "tt6gm2a0463x9wmnx7rn6gugc",
                    "label": "5",
                    "tags": [
                        "laundry"
                    ],
                    "dimensions": {
                        "areaFloor": 5.239500045776367,
                        "areaFloorIndoor": 5.239500045776367,
                        "areaWall": 25.518861770629883,
                        "volume": 15.819963455200195,
                        "height": 3.019364833831787,
                        "units": "metric"
                    }
                },
                {
                    "id": "kuc0fpmsgqxff63egrxrycfud",
                    "label": "16",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 19.056400299072266,
                        "areaWall": 54.98054504394531,
                        "volume": 57.81614303588867,
                        "height": 3.0339488983154297,
                        "units": "metric"
                    }
                },
                {
                    "id": "wbpb7dkfuwnikd1kq2a9hz70a",
                    "label": "14",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 1.646399974822998,
                        "areaWall": 4.429454803466797,
                        "volume": 4.219707489013672,
                        "height": 2.562990665435791,
                        "units": "metric"
                    }
                },
                {
                    "id": "b4qtykzcazp4iumkamm7y7h2b",
                    "label": "12",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 12.713900566101074,
                        "areaFloorIndoor": 12.713900566101074,
                        "areaWall": 38.93343734741211,
                        "volume": 32.931732177734375,
                        "height": 2.590214729309082,
                        "units": "metric"
                    }
                },
                {
                    "id": "3m54yff1z7crxaywd8if9rb0d",
                    "label": "7",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.156899929046631,
                        "areaFloorIndoor": 4.156899929046631,
                        "areaWall": 24.900320053100586,
                        "volume": 12.581944465637207,
                        "height": 3.026761531829834,
                        "units": "metric"
                    }
                },
                {
                    "id": "a5f9age4zzxewres6iqux2emc",
                    "label": "9",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.8993000984191895,
                        "areaFloorIndoor": 4.8993000984191895,
                        "volume": 12.761096954345703,
                        "height": 2.604677438735962,
                        "units": "metric"
                    }
                },
                {
                    "id": "cdz3fkt38kae7tapstpt0eaeb",
                    "label": "3",
                    "tags": [
                        "kitchen",
                        "living",
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 102.59071350097656,
                        "areaFloorIndoor": 102.59071350097656,
                        "areaWall": 184.97195434570312,
                        "volume": 657.700927734375,
                        "units": "metric"
                    }
                },
                {
                    "id": "ediidma5zg15dufx3n0qyq21a",
                    "label": "13",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 24.611000061035156,
                        "areaFloorIndoor": 24.611000061035156,
                        "areaWall": 49.6417236328125,
                        "volume": 81.93767547607422,
                        "units": "metric"
                    }
                },
                {
                    "id": "xy2x8mpaaqknp7q2c3nnbw1ma",
                    "label": "4",
                    "tags": [
                        "dining",
                        "living"
                    ],
                    "dimensions": {
                        "areaFloor": 17.3887996673584,
                        "areaFloorIndoor": 17.3887996673584,
                        "areaWall": 46.00373458862305,
                        "volume": 52.49049758911133,
                        "height": 3.0186383724212646,
                        "units": "metric"
                    }
                },
                {
                    "id": "2qdmc5i9byxi79ry1pxdkqzea",
                    "label": "8",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 15.340200424194336,
                        "areaFloorIndoor": 15.340200424194336,
                        "areaWall": 41.409175872802734,
                        "volume": 57.230098724365234,
                        "units": "metric"
                    }
                },
                {
                    "id": "m8npxsuk79xy21dd09x9wtped",
                    "label": "11",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 4.3730998039245605,
                        "areaFloorIndoor": 4.3730998039245605,
                        "areaWall": 15.520317077636719,
                        "volume": 11.225411415100098,
                        "height": 2.566923141479492,
                        "units": "metric"
                    }
                },
                {
                    "id": "n81qfe51azs8iexnbqwspye6c",
                    "label": "15",
                    "tags": [
                        "office"
                    ],
                    "dimensions": {
                        "areaFloor": 4.414400100708008,
                        "areaWall": 18.9549503326416,
                        "volume": 13.287762641906738,
                        "height": 3.0100948810577393,
                        "units": "metric"
                    }
                },
                {
                    "id": "19ab05tns5h6y4qm42esqqpea",
                    "label": "10",
                    "tags": [
                        "bedroom",
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 19.325401306152344,
                        "areaFloorIndoor": 19.325401306152344,
                        "areaWall": 64.1736068725586,
                        "volume": 71.8935775756836,
                        "units": "metric"
                    }
                },
                {
                    "id": "613htqkzf66zz7hf7n8kzszed",
                    "label": "2",
                    "tags": [
                        "living"
                    ],
                    "dimensions": {
                        "areaFloor": 22.022300720214844,
                        "areaFloorIndoor": 22.022300720214844,
                        "areaWall": 48.04021453857422,
                        "volume": 66.34620666503906,
                        "height": 3.0126829147338867,
                        "units": "metric"
                    }
                }
            ]
        }
    }
}

Try this query in our interactive console

Get the Colored Rooms Floorplan URL
query getColoredRooms($modelId: ID!){
 model(id: $modelId) {
    assets {
      floorplans(provider: "matterport", flags: [colored_rooms]) {
        provider
        format
        flags
        id
        url
      }
    }
  }
}

# variables
{
  "modelId" : ""
}

Sample Response:

{
  "data": {
    "model": {
      "assets": {
        "floorplans": [
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_000.jpg?t=2-45286ff9b37da4d31d06a13b828c497d00343f7c-1679975423-1&download=colorplan_room_000.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_000.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_001.jpg?t=2-3377428ace2fcebeb51b5a24d55aff51ad6b85db-1679975423-1&download=colorplan_room_001.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_001.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_002.jpg?t=2-878d69a6f66558f17271e17b4c4f5a03b606368f-1679975423-1&download=colorplan_room_002.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_002.jpg"
          },
          {
            "provider": "matterport",
            "format": "jpg",
            "flags": ["photogramy", "colored_rooms"],
            "id": null,
            "url": "https://cdn-2.matterport.com/models/58f2a24ec7fb43abaf68c39459cd29d3/assets/render/colorplan_room_003.jpg?t=2-0dd57e99aa752e228ef2d85b9aff89f8663b826b-1679975423-1&download=colorplan_room_003.jpg&k=models%2F58f2a24ec7fb43abaf68c39459cd29d3%2Fassets%2Frender%2Fcolorplan_room_003.jpg"
          }
        ]
      }
    }
  }
}

Try this query in our interactive console

Get all Notes and Comments

Users can query notes that have been created in Matterport Cloud to synchronize information within their internal applications.

query getNotes($modelId: ID!){
  model(id:$modelId) {

  notes(includeDisabled: true,
        # resolutionStatus: [resolved],
        #ids: ["_____"]
  ) {
    id
    created
    modified
    label
    enabled
    createdBy {
      id
      firstName
       lastName
       email
    }
    resolution
    color
    anchorPosition { x y z }
    discPosition { x y z }
    stemNormal { x y z }
    stemLength
    stemEnabled
    firstCommentAt
    lastCommentAt
    totalComments
    ...Comments
    }
  }
}

fragment Comments on Note {
  comments(sortBy: { field: created }, pageSize: 1, offset: "string") {
    nextOffset
    results {
      id
      created
      modified
      createdBy {
        id
        firstName
        lastName
        email
      }
      edited
      text
    }
  }
}

# variables
{
  "modelId" : ""
}

Try this query in our interactive console

Mutations

Mutations update data via Model API. They can also contain queries that return data after the data has changed. The query can return an ID if new content has been added, or updated information that may have changed due to the patch (update).

Toggle Model Visibility and Get Embed URL
mutation toggleModelVisibility($modelId: ID!, $visibility: ModelVisibility!){
  updateModelAccessVisibility(id: $modelId, visibility: $visibility) {
    id
    accessVisibility
    accessVisibilityLastChanged
    publication {
      published
      url
      externalUrl
      embed
    }
  }
}

# variables
{
  "modelId" : "",
  "visibility" : "public"
}

Sample Response:

{
  "data": {
    "updateModelVisibility": {
      "id": "WeZ1dHwn3ac",
      "publication": {
        "published": true,
        "url": "https://my.matterport.com/show/?m=WeZ1dHwn3ac",
        "externalUrl": null,
        "embed": "<frame width='853' height='480' src='https://my.matterport.com/show/?m=WeZ1dHwn3ac' frameborder='0' allowfullscreen allow='xr-spatial-tracking'></iframe>"
      }
    }
  }
}

Try this query in our interactive console

Toggle Model Activation (archive / activate)
mutation toggleModelActivation($modelId: ID!, $state: ModelStateChange!) {
  updateModelState(id: $modelId, state: $state) {
    id
  }
}

Try this query in our interactive console

Patch Model Details

Model API can be used to change the default settings for a model and all meta information associated with it using the patchModel mutation.

mutation toggleModelVisibility($id: ID!){
  patchModel(id: $id, patch: {
      name: "Model Name",
      description: "Model Description",
      options: {
          # For all following options:
          # default, enabled, disabled
          socialSharingOverride: default,
          vrOverride: default,
          tourButtonsOverride: default,
          tourAutoplayOverride: default,
          dollhouseOverride: default,
          dollhouseLabelsOverride: default,
          floorplanOverride: default,
          labelsOverride: default,
          highlightReelOverride: default,
          unitType: {
              set: metric, # or imperial
              resetToDefault: false
          },
          # Special options:
          measurements: {
            # disabled, measure, measureAndView
            set: measureAndView,
            resetToDefault: false
          },
          backgroundColor: {
              # black, grey, white
              set: white,
              resetToDefault: false
          },
      }
      mls: {
          id: "MLS ID",
          name: "Listing Name"
      },
      publication: {
          contact: {
              name: "Contact Person",
              email: "person@domain.com",
              phoneNumber: "888-888-8888"
          }
          externalUrl: "https://linktomoreinfo.com",
          presentedBy:"Your Company Name",
          summary: "Summary information about this model."
      },

  }) {
    id
    name
    description
    options {
          socialSharingOverride,
          vrOverride,
          tourButtonsOverride,
          tourAutoplayOverride,
          dollhouseOverride,
          dollhouseLabelsOverride,
          floorplanOverride,
          labelsOverride:,
          highlightReelOverride,
          unitType,
          measurements,
          backgroundColor
    }
    mls {
        id
        name
    }
    publication {
          contact {
              name
              email
              phoneNumber
          }
          presentedBy
          externalUrl
          summary
      }
  }
}

# variables
{
    "id" : "FE1FLGnch5h"
}

Sample Response:

{
  "data": {
    "patchModel": {
      "id": "FE1FLGnch5h",
      "name": "Model Name",
      "description": "Model Description",
      "options": {
        "socialSharingOverride": "default",
        "vrOverride": "default",
        "tourButtonsOverride": "default",
        "tourAutoplayOverride": "default",
        "dollhouseOverride": "default",
        "dollhouseLabelsOverride": "default",
        "floorplanOverride": "default",
        "labelsOverride": "default",
        "unitType": "metric",
        "measurements": "measureAndView",
        "backgroundColor": "white"
      },
      "mls": {
        "id": "MLS ID",
        "name": "Listing Name"
      },
      "publication": {
        "contact": {
          "name": "Contact Person",
          "email": "person@domain.com",
          "phoneNumber": "(888) 888-8888"
        },
        "presentedBy": "Your Company Name",
        "externalUrl": "https://linktomoreinfo.com",
        "summary": "Summary information about this model."
      }
    }
  }
}

Try this query in our interactive console

Change Address Visibility

Model API can be used to change the default settings for a model and all meta information associated with it using the patchModel mutation.

mutation changeAddressVisibility($id: ID!){
    updateModelAddress(
      id: $id,
      addressVisibility: none     # full, partial or none
    ) {
        options {
            addressVisibility
        }
    }
  }

# variables
{
    "id" : "FE1FLGnch5h"
}

Sample Response:

{
  "data": {
    "updateModelAddress": {
      "id": "FE1FLGnch5h",
      "name": "Model Name",
      "options": {
        "addressVisibility": "none"
      }
    }
  }
}

Try this query in our interactive console

Add a Tag

Adding a Tag requires a valid floorId, which you can get by querying floors before performing an addMattertag mutation.

mutation addTag(
  $modelId: ID!,
  $floorId: ID!,
  $color: String,
  $description: String,
  $label: String,
  $icon: String,
  $keywords: [String!],
  $enabled: Boolean!,
  $anchorPositionX: Float!,
  $anchorPositionY: Float!,
  $anchorPositionZ: Float!,
  $stemEnabled: Boolean!,
  $stemNormalX: Float!,
  $stemNormalY: Float!,
  $stemNormalZ: Float!,
  $mediaType: MattertagMediaType,
  $mediaUrl: String,
  $stemLength: Float!
){
  addMattertag(
    modelId: $modelId,
    field: id,
    mattertag: {
      floorId: $floorId, # Must be valid
      enabled: $enabled, # required and can be true or false
      color: $color,
      label: $label,
      icon: $icon,
      keywords: $keywords,
      description: $description,
      anchorPosition: { x: $anchorPositionX, y: $anchorPositionY, z: $anchorPositionZ },
      mediaType: $mediaType,
      mediaUrl: $mediaUrl,
      stemEnabled: $stemEnabled,
      stemNormal: { x : $stemNormalX , y: $stemNormalY, z: $stemNormalZ },
      stemLength: $stemLength
    }
  ) {
    id
  }
}

# variables
{
  "modelId" : "",
  "floorId": "pd0i1c4yq9w0y2zsb07ed23sb",
  "color": "#03687d",
  "label": "Updated Tag",
  "icon": "public_symbols_video",
  "keywords" : ["API Tag", "Test Patch Tag"],
  "description": "This Tag was updated!",
  "enabled" : true,
  "anchorPositionX" : 1.20415628,
  "anchorPositionY" : -5.3543434,
  "anchorPositionZ" : 3.1942153,
  "stemNormalX" : 1.0,
  "stemNormalY" : 0.0,
  "stemNormalZ" : 0.0,
  "mediaType" : "video",
  "mediaUrl" : "https://www.youtube.com/watch?v=dAdsl9x_Dyw",
  "stemEnabled" :  true,
  "stemLength" :  0.16459
}

Try this query in our interactive console

Patch a Tag

Patching a Tag requires providing the tag Id.

mutation patchTag(
  $modelId: ID!,
  $tagId: ID!
  $floorId: ID!,
  $color: String,
  $description: String,
  $label: String,
  $icon: String,
  $keywords: [String!],
  $enabled: Boolean!,
  $anchorPositionX: Float!,
  $anchorPositionY: Float!,
  $anchorPositionZ: Float!,
  $stemEnabled: Boolean!,
  $stemNormalX: Float!,
  $stemNormalY: Float!,
  $stemNormalZ: Float!,
  $mediaType: MattertagMediaType,
  $mediaUrl: String,
  $stemLength: Float!
){
  patchMattertag(
    modelId: $modelId,
    field: id,
    mattertagId: $tagId,
    patch: {
      floorId: $floorId, # Must be valid
      enabled: $enabled, # required and can be true or false
      color: $color,
      label: $label,
      icon: $icon,
      keywords: $keywords,
      description: $description,
      anchorPosition: { x: $anchorPositionX, y: $anchorPositionY, z: $anchorPositionZ },
      mediaType: $mediaType,
      mediaUrl: $mediaUrl,
      stemEnabled: $stemEnabled,
      stemNormal: { x : $stemNormalX , y: $stemNormalY, z: $stemNormalZ },
      stemLength: $stemLength
    }
  ){
    id # Returns Tag ID
  }
}

# variables
{
  "modelId" : "",
  "tagId" : "ayi201wkujs",
  "floorId": "pd0i1c4yq9w0y2zsb07ed23sb",
  "color": "#03687d",
  "label": "Updated Tag",
  "icon" : "public_symbols_video",
  "keywords" : ["API Tag", "Test Patch Tag"],
  "description": "This Tag was updated!",
  "enabled" : true,
  "anchorPositionX" : 1.20415628,
  "anchorPositionY" : -5.3543434,
  "anchorPositionZ" : 3.1942153,
  "stemNormalX" : 1.0,
  "stemNormalY" : 0.0,
  "stemNormalZ" : 0.0,
  "mediaType" : "video",
  "mediaUrl" : "https://www.youtube.com/watch?v=dAdsl9x_Dyw",
  "stemEnabled" :  true,
  "stemLength" :  0.16459
}

Try this query in our interactive console

Multiple Mutations as a Single Request

GraphQL mutations send requests to our platform wherein a specific task is performed. Some tasks include simple changes to database fields, while other requests such as unarchiving a model may involve multiple tasks on our platform.

If an application needs to send multiple mutations, it may be critical that these mutations execute in a specific order to prevent race conditions. For instance, if an automation is written whereby a model is set to unlisted and then a floorplan is purchased, if two mutations are sent, the floorplan purchase request may trigger first. If the model state has not changed to ‘unlisted’, the request to purchase the floorplan will fail as models must be set to public or unlisted.

[Learn more about using Multihttps://graphql.org/learn/queries/#multiple-fields-in-mutations

Activate a Model, Set it to Unlisted, Purchase a Floorplan
mutation activateAndPurchase($modelId: ID!) {
  updateModelState(id: $modelId, state: active) {
    id
    state
  }
  updateModelAccessVisibility(id: $modelId, visibility: public) {
    id
    accessVisibility
    accessVisibilityLastChanged
  }
  unlockModelBundle(id: $modelId, bundleId: "floorplan:schematic",
    options: { deliverySpeed: normal }
  ){
    id
    name
    description
    availability
    assets { url }
  }
}

# variables
{
  "modelId" : ""
}

Try this query in our interactive console

Ordering Add-Ons

For code snippets related to purchasing add-ons, please visit the Ordering Assets Page.