November 21, 2024

Enterprise Users

  • WebHooks v2.0 is now available with a body payload that contains information about what changes have triggered the webhook event. For more information, please refer to our Webhooks Documentation.
  • For all Enterprise API users, we strongly encourage integrating WebHooks into your automation flows to improve efficiency and to enable reliable synchronization between your internal records and the content within your Matterport Account.

API Changes

  • organizationId has been deprecated on the addOrUpdateModelShareAccess and addOrUpdateFolderShareAccess mutations.

October 31, 2024

All Users

  • Exposed AI description within *model { publication { description } } * for both single model and search queries
  • Clarified that model { description } maps to the field labelled “Internal Notes” in my.matterport.com

October 9, 2024

Enterprise Users

  • Exposed ceiling { maxHeight, minHeight } in model room dimensions

July 31, 2024

Schematic Floorplans can now be ordered with additional options including color, furniture and a custom logo. Users can also query individual files within purchased schematic floorplan bundles.

For more information, please refer to our Ordering Add-Ons Page.

July 10, 2024

Minor update:

  • Remove @beta from Property Intelligence API Objects

June 20, 2024

Minor update:

  • Deprecated model.visibility in favor of model.accessVisibility

April 25, 2024

Layers are now partially exposed by Model API. Users can now query layers on any object and obtain a list of layers for any view. Learn More.

Password Protected and Public (available on Discover) visibilities can now be seen and set. Previously only private and unlisted were possible.

  • The new accessVisibility attribute returns private, unlisted, public or password
  • The new accessVisibilityLastChanged attribute returns the date/time when visibility was last changed.
  • The new updateModelAccessVisibility mutation will allow a user to set the visibility of a space to all four visibility options as well as set passwords on password protected spaces.
mutation UpdateModelAccessVisibility {
    updateModelAccessVisibility(id: "RHcNJBGQyzo", visibility: password, password: "test") {
        id
        accessVisibility
        accessVisibilityLastChanged
    }
}

A user may also now get the total number of scans with the model.assets.sizeEstimates attribute. This count is often used when assessing the availability or price of an add-on.

query {
    model(id: "qrsvVuvhfb6") {
        assets {
            sizeEstimates {
                scanCount
            }
        }
    }
}

Response:

{
    "data": {
        "model": {
            "assets": {
                "sizeEstimates": {
                    "scanCount": 1
                }
            }
        }
    }
}

Enterprise Only

folder.models query now allows activationStates parameter which can be active, archived, pending or flagged. Flagged models are models that are pending approval due to being captured in unauthorized geo-blocked locations.

query Folder {
    folder(id: "BP1w3rrfjp8") {
        subfolders(pageSize: 100) {
            results {
                name
                id
            }
        }
        models(pageSize: 100, activationStates: archived) {
            nextOffset
            totalResults
            results {
                state
                name
                id
                created
                description
                address {
                    address
                }
                image {
                    resizeUrl(resolution: preview)
                }
                publication {
                    summary
                }
            }
        }
    }
}

January 18, 2024

All Users

Models can now be deleted via Model API

deleteModel(id: ID!, field: ModelIdField): Boolean mutation is now Public

Enterprise Users

This is a major revision exposing data from Property Insights. At this time, only Enterprise customers who have been enrolled in our beta can access the data.

The queries and mutations are available to all public API users, however dimensionEstimates and the room boundary data used to generate the area estimates will only be populated for models processed after the start of November 2023.

  • New Mutations: addBoundaryVertex, addBoundaryEdge, addRoom, bulkPatchRoomData, patchBoundaryVertex, patchBoundaryEdge, addEdgeOpenings, removeEdgeOpenings, patchEdgeOpening, patchRoom, deleteRoomsAndBoundaryData
  • New Queries: Model { roomClassifications, dimensionEstimates}, ModelRoom { dimensionEstimates, boundary, holes, classifications, keywords }, ModelFloor { dimensionEstimates, vertices, edges }
  • New Types / Inputs: RoomClassification, Dimensions, DimensionData, DimensionPatch, DimensionDataPatch, BoundedRegion, Vertex, Edge, Opening, BoundedRegionDetails, VertexDetails, EdgeDetails, OpeningDetails, RoomDetails, RoomAssociations, RoomDataSelection
  • New Enums: RoomDataType, OpeningType, EdgeType

November 15, 2023

Views are now a part of Model API! Documentation

  • mutations: addView, deleteView, and copyViewData
  • queries: model.views

Aug 8, 2023

  • Private Model Embed (PME) no longer requires also having the OAuth feature enabled on the organization. Nothing changes from a usage perspective.

May 16, 2023

  • A new BillingDetails under model, containing exempt: Boolean and multiSpaceUse
    • multiSpaceUse is the number of spaces counted against your space quota
    • Models on Classic Accounts or that were uploaded to accounts before entering into our new billing plans will always have a multiSpaceUse value of 1
  • The Mutation updateModelState now accepts an allowActivate boolean which defaults to false.
    • This must be set to true to unarchive models on accounts that would incur reactivation charges.
    • If this is unspecified or set to false on an account that would incur reactivation charges a request.unsupported error code will be returned.

April 6, 2023

  • Users with Folder API Access can now query folder paths within model queries.
query getModelFolder {
  model(id: $modelId) {
    folders {
      id
      depth
    }
  }
}

March 1, 2023

API Changes

  • The assets attribute on Model is marked as nullable and documented with @error model.inactive
  • The updateModelAddress mutation supports changing the addressVisibility property.
  • The model mutation updateAddress supports changing the addressVisibility property.

Bug Fixes and Other Enhancements

  • Model Webhooks bugs have been fixed and users should receive notifications for all models in their organization.

January 18, 2023

  • The icon attribute on Mattertags may now be read and patched. Please see Tags 2.0 Icons Reference for the full icon set.
  • The floor attribute on Labels may now be queried and mutated.
  • Added ID for the resource (denoting SID of the resource) in AccessInfo type for access query

December 14, 2022

  • Folder and model api query for access now in @beta
  • The HTTP status code will be more accurate in cases where the entire graph query fails to process.
  • The error structure will also now include an additional httpStatus attribute which indicates what the equivalent HTTP status for each sub-error would have been

Example model query:

query model {
  model(id: "$modelId") {
    access(pageSize: 30, orderBy: ROLE, filters: [Admin]) {
      results {
        email
        type
        role
        name
      }
      nextOffset
    }
  }
}

Example folder query:

query folder {
  folder(id: "$folderId") {
    id
    name
    access(filters: [FolderCreator], pageSize: 500) {
      results {
        email
        name
        role
        type
      }
      nextOffset
    }
  }
}

November 16, 2022

October 26, 2022

  • Folder extensions now out of @beta
  • Webhook Mutations now available. (Enterprise only)
mutation {
  addModelEventWebhookCallback(ModelEventCallbackInput) { ... }
}

mutation {
  patchModelEventWebhookCallback(
    id: ID!,
    input: ModelEventCallbackInput
  ): ModelEventWebhookCallback
}

mutation {
  removeModelEventWebhookCallback(id: ID!): Boolean
}

mutation {
  pingModelEventWebhookCallback(id: ID!): Boolean
}

mutation {
  addModelEventToCallback(
    id: ID!,
	eventTypes: [ModelEventType!]
  ): ModelEventWebhookCallback
}

mutation {
  removeModelEventFromCallback(
    id: ID!,
	eventTypes: [ModelEventType!]
  ): ModelEventWebhookCallback
}

October 12, 2022

This changes the default serialization of fields with errors or no data from being left out of the response to serializing null explicitly (this is more compliant with the GraphQL standard). There is a graph query which may be used to opt an org out of this behavior to the previous behaviour:

query getSerialization($orgId: ID) {
  organization(id: $orgId) {
    id
    developer {
      options {
        serializeGraphNulls
      }
    }
  }
}

mutation disableSerializeNulls($orgId: ID) {
  patchDeveloperOptions(organizationId: $orgId, serializeGraphNulls: disabled) {
    serializeGraphNulls
  }
}

mutation enableSerializeNulls($orgId: ID) {
  patchDeveloperOptions(organizationId: $orgId, serializeGraphNulls: enabled) {
    serializeGraphNulls
  }
}

Bug Fixes and Other Enhancements

  • Fixed a bug where the query to get the organization’s root folder was not returning results.

September 21, 2022

  • Mattertag description max length increased from 1,000 characters to 2,000 characters

September 7, 2022

This release exposes full folder manipulation (within org) create, edit, share, move and delete folders.

This is currently a closed beta that can be enabled via the api.graph.ext.folders policy.

API Changes

  • Add query to get folder and root folder for an organization.
query {
	folder(id: ID!): Folder
}

query {
	rootFolder(organizationId: ID): Folder
}
  • Add mutation to create, edit, delete and move folders within organization
mutation {
	addFolder(folderDetails: FolderDetails!): Folder
}

mutation {
	patchFolder(id: ID!, patchInput: FolderPatch!): Folder
}

mutation {
	moveToFolder(modelIds: [ID!], folderIds: [ID!], destinationFolderId: ID!): Folder
}

mutation {
	deleteFolder(id: ID!): Boolean
}
  • Add mutation to add, update and remove shares for model and folders

mutation {
	removeModelShareAccess(userId: ID!, modelId: ID!): Boolean!
}

mutation {
	removeFolderShareAccess(userId: ID!, folderId: ID!): Boolean!
}

mutation {
	addOrUpdateModelShareAccess(userId: ID!, roleId: ID!, modelId: ID!): UserModelShareAccess
}

mutation {
	addOrUpdateFolderShareAccess(
		email: String,
		userId: ID,
		invitationMessage: String,
		roleId: ID!,
		folderId: ID!
	): UserFolderShareAccess
}

August 24, 2022

This is a minor revision related to the object detection beta.

API Changes

  • Add a parameter to Model.objectAnnotations() to explicitly include user created ObjectAnnotations
query {
	objectAnnotations(
		includeUserCreated: Boolean
	): [ObjectAnnotation!]
}

June 15, 2022

This release exposes the initial schema for object annotations (object detection/insights), data will only be available for folks included in the invite only evaluation.

Also included in this release is the initial implementation of Private Model Embed (PME), the next-gen replacement for Private Model Access (PMA).

API Changes

  • [CLOSED BETA] As part of the internal beta of Object Detection the following schema will be made public but data will only be populated for members of the closed beta.
type Model {
  inferenceEvents(ids: [ID!]): [InferenceEvent!]
  objectClassifications: [ObjectClassification!]
  objectAnnotations(
    inferenceEvents: [ID!]
    ids: [ID!]
    includeDisabled: Boolean
    minimumConfidenceOverride: Float
  ): [ObjectAnnotation!]
}

type InferenceEvent {
  id: ID!
  created: DateTime!
  detectionModelName: String!
  detectionModelVersion: String!
}

type ObjectClassification {
  id: ID!
  label: String!
  defaultKeywords: [String!]
}

type ObjectAnnotation implements Annotation {
  id: ID!
  created: DateTime!
  modified: DateTime!
  model: Model
  source: ObjectAnnotationSource!
  floor: ModelFloor
  room: ModelRoom
  enabled: Boolean!
  label: String
  confidence: Float
  panos: [PanoramicImageLocation!]
  region: Region
  tag: Mattertag
  keywords: [String!]
  classification: ObjectClassification
}

type Mattertag {
  objectAnnotation: ObjectAnnotation
}

May 26, 2022

This release adds ability to get information about user(s) who have uploaded the model.

  • For all models created to date this will always be a single user, however this will expand out to allow multiple uploaders as the capture app evolves
query {
  model(id: ID!) {
    uploaders: [UserMetadata]
  }
}

May 4, 2022

This is a minor feature release to expose more information about bundle status.

  • Additional information about the status of bundles that are being processed.
  • The processing field on bundles is made public, the following attributes will now be available under that for any bundles that have been unlocked:
query {
  model(id: ID!) {
    bundle(id: "mp:matterpak") {
      processing {
        bundleId: String!
        organizationId: ID!
        status: BundleProcessingStatus!
        lastModified: DateTime!
        failureCode: String
        failureReason: String
      }
    }
  }
}

Note that failureCode and failureReason are specific to each bundle type

April 14, 2022

This is a major feature release to expose notes functionality over the public apis as well as clean up doc a bit and refresh the experience.

  • Exposed Note Query and Mutations
  • Deprecated updateMattertagMedia and enabled updating the external URL via patchMattertag
  • API doc experience refreshed and more closely integrated with SDK doc

March 22, 2022

  • Exposed a generate assets request which will allow assets for bundles to be generated on demand.

December 16, 2021

  • Fixed a type in measurmentPath to be measurementPath under rooms.

July 29, 2021

  • Added a 1,000 page limit to the models query, this also fixed an issue where asking for a page size of 10,000 or more results would cause nextOffset to not be populated even when there were additional hits.

May 13, 2021

  • Fixed an issue that allowed an API token to access models that the token creator had access to outside of the token’s organization. Note that this includes restricting access to public models outside of the organization the token belongs to.

April 22, 2021

This release adds official support for controlling more options related to the Matterport Showcase and additional information associated with public models.


query {
	model(id: ID!) {
		options {
			addressVisibility
			tourButtonsEnabled
			tourButtonsOverride
			dollhouseEnabled
			dollhouseOverride
			floorplanEnabled
			floorplanOverride
			labelsEnabled
			labelsOverride
			dollhouseLabelsEnabled
			dollhouseLabelsOverride
			highlightReelEnabled
			highlightReelOverride
			tourAutoplayEnabled
			tourAutoplayOverride
			backgroundColor
			unitType
			measurements
			address
		}
	}
}

mutation {
	patchModel(
		id: ID!,
		patch: {
			options: {
				backgroundColor: BackgroundColorSettingOverride
				tourButtonsOverride: SettingOverride
				dollhouseOverride: SettingOverride
				floorplanOverride: SettingOverride
				labelsOverride: SettingOverride
				dollhouseLabelsOverride: SettingOverride
				highlightReelOverride: SettingOverride
				tourAutoplayOverride: SettingOverride
				unitType: UnitSettingOverride
				measurements: MeasurementsModeOverride
			}
		}
	)
}

March 29, 2021

  • Removed some leaked references to internal API structures

February 11, 2021

This is a maintenance release with updates focused on addressing integration concerns and preparing for expanded add ons in the future.

  • Added an estimate of the total dimensions of the space under Model.dimensions
  • GSV and homeaway bundles will now show up as locked if they are associated with a compatible model but it is still not possible to unlock them via the API.

December 17, 2020

The focus of this release is continued bug fixing / enhancements to enable workshop / showcase to operate over the new graph API.

  • Made all fields which may return an error (such as unauthorized or not found) to be nullable (removed the exclamation mark). This will allow partial data to be returned in a wider variety of cases but may result in changes to generated clients.
  • Added a patch photo mutation to allow the label associated with a photo to be updated.

November 5, 2020

Data Model Changes

  • Some objects had legacy identifiers which were integer values, switched all objects to use a consistent unique id format.
  • The identifiers for the following objects were updated:
    • AnchorLocation
    • Label
    • Mattertag
    • Measurement
    • PanoramicImageLocation

  • All coordinates that are exposed were updated to use the same coordinate system that is used for the mesh (seen on location objects). This resulted in changing the coordinate system for Measurements and Mattertags. Measurements were in the wrong coordinate system and there was a bug in translating Mattertag coordinates.

  • Convert SDK coordinates to Mesh (API)
let api.x = sdk.x
let api.y = invert(sdk.z)
let api.z = sdk.y
  • Convert Mesh (API) coordinates to SDK
let sdk.x = api.x
let sdk.y = api.z
let sdk.z = invert(api.y)
  • Mutation patchFloor updated to return ModelFloor instead of Model
  • The Measurement object has been deprecated in favor of MeasurementPath, while old Measurement queries will still be syntactically valid they will return no data.
  • Skybox tile related information has been removed
  • Texture type was changed to quality and type is now a string representing the file format

API Changes

  • Added MeasurementPath queries and mutations
  • Added HighlightReel queries and mutations
  • Additional information about placement of photos within a model
  • Exposed information about demo models
  • Added filtering options to several queries
  • Addition of the mp:imagery bundle for purchasing high resolution panoramic images

Bug Fixes and Other Enhancements

  • Addition of the mp:imagery bundle for high resolution panoramic images
  • Performance improvements
  • Addition of a sandbox mode for demonstrating the API
  • Dedicated developer settings section

May 28, 2020

Breaking Changes

  • ModelFloor zIndex has been removed
  • Removed attributes from ModelMutator addMattertag and MattertagMutator patch mutations
    • position - Use anchorPosition instead
    • stemDirection - Use stemNormal and stemLength instead

API Changes

  • Added attributes to ModelFloor (Query)
    • meshId: int (read-only) - The vision generated ID for the floor.
    • classification: string (read-only) - The capture generated label for the floor. This is initially used to populate the label field, but the label field may be modified by public clients, whereas this will maintain the initial value.
  • Added attributes to Mattertag (query & mutation)
    • roomId: ID - The room that the Mattertag is in. This is not spatially validated by the API, just checks that the requested room exists.
  • Removed attributes from ModelMutator Mattertag mutations