Matterport APIs Overview

No authorization token is present, or the authorization token has expired.

User attempted to access an operation or field that is not allowed.

The graph query could not be processed.

The server was unable to process the request.

The requested object doesn’t exist. You will see this error when using the specific ID field in the associated operation.

An attempt was made to retrieve a single record from a secondary index, but multiple records matched the submitted query. This often happens when multiple models have the same internal ID.

Resource limited mutations. For example, attempting to activate more models than allowed due to subscription limitations

API is short for application programming interface. This is a communications protocol between different parts of a computer program. The main intention of an API is to simplify the implementation and maintenance of software.

Matterport APIs allow developers or customers to programmatically connect their systems or applications directly to the Matterport system in order to access and modify data.

The Showcase SDK is a client-side JavaScript client and library that can be used by developers to extend Showcase capabilities, even if the Showcase is directly embedded on another site or platform. Think of it as a thin, invisible layer that sits on top of the Showcase iFrame, only on the developer’s page. With that in mind, the SDK affects the experience only on one developer page per use. As such, models that have been shared on multiple sites are affected only on the developer’s page where the SDK has been applied.

As opposed to the SDK, the API connects directly __ to the Matterport backend. This allows developers to perform a variety of commands, like searching, reading data, changing data, and placing orders. The Matterport API allows developers to programmatically perform actions that customers take in Matterport Cloud and includes access to some data not publically available.

We recommend only using the API to access the customer’s account and models. __ Keep in mind, the API token is essentially a set of administrative credentials, and provides full access to the account, even to make purchases via API.

Matterport currently offers two APIs:

Model API Search, read, and change model data, including model details like the name and address of the space, sharing URLs, images, videos, position data, the OBJ mesh file, the point cloud file, panoramic imagery, position points, and Tags.

Account API (available only with Enterprise subscription tiers) - These commands include managing users, inviting, updating permissions, and managing SDK keys.

Matterport also offers Enterprise-only extensions to these APIs:

Folders API - An extension to both Model and Account APIs that provides the ability to manage folders, move models between folders and query models by folders.

Webhooks - An extension to Model API. Add callback events that send information to your platform when changes are made within your account including when models are uploaded, processed, edited or removed.

Private Model Embed Mutations - An extension to Model API. Create private model embed links with a short-lived access token for displaying models within your private Intranet.

You need to have a developer tools license on any of our Enterprise SaaS Tiers. If you do not currently have a Developer Tools license, please contact your Enterprise account manager to add this to your contract.

You’ll need to request an API token. To do so:

1. Go to Matterport Cloud (my.matterport.com)
2. Click Settings in the lower left.
3. Select Developer Tools.
4. Go to the API Token Management section. Here, you can request and revoke API keys.

How you write your query depends on the HTTP method and content-type you specify. Per the GraphQL spec, the request can be sent as either GET or POST.

GET requests - The parameters must be properly escaped in the query string.

POST requests - This should include a JSON-encoded body, illustrated in this article.

Use this URL in your GET and POST requests: https://api.matterport.com/api/models/graph

Try a sample GET request (using the URL above)

Sample cURL request:

Authorization: Basic <b>[base64 encoded apiToken:apiSecret]</b>

curl \
--user [apiKey]:[apiSecret] \
-v 'https://api.matterport.com/api/models/graph?query=\{models\{totalResults%20results\{id%20created%20modified%20visibility\}\}\}'

Notice the symbols above taken from the cURL request - these are escaping for bash. The cURL will not automatically URL encode whitespace, which is why the %20 is added.

This is a bit confusing, but is expected behavior. The Showcase SDK is designed to work from the perspective of the camera, so its coordinate system rotates to determine the Y axis (height) and Z axis (depth). If you were to download a MatterPak, you would find all of the coordinate information with Z-up. The SDK hides this by only exposing certain pieces of information.

The pseudo-code for doing the translation is as follows:

def fromSdkToApi(x, y, z) = [ x, -z, y ]
def fromApiToSdk(x, y, z) = [ x, z, -y ]

Note that the translation above may seem odd because the Z and Y coordinates are both flipped, and one is inverted.

This happens because of caching in our CDN. An edit/publish flow will fully flush the CDN cache, though we don’t currently do that for every edit at the API layer.

One way to verify that you’re experiencing a CDN cache issue is to look at the model in a private or incognito window. Authenticated users will bypass the cache but anonymous viewers will not. If this is the case, changes should be visible to everyone within an hour.

No, the API can only currently get and set model details, assets, Mattertags, labels, and bundles.

Use the query below:

import requests 

token = 'Your API token' 
secret = 'Your secret API token' 
endpoint = 'https://api.matterport.com/api/models/graph'
query = { 'query' :
    '''
    query {
      models(query: "*"){
        totalResults
        results{ id }
      }
    }
    '''
}
auth = (token, secret)
headers = {'content-type': 'application/json', 'accept':'gzip'}
r = requests.post(endpoint, json=query, auth=auth, headers=headers) 

if(r.ok):
    print(r.json())
else: 
    print(r.status_code)

If you are set as a collaborator (as opposed to an admin), you cannot access models through the API.

If you need access, you have two options:

1. Request that an account admin transfers the space to you.
2. Have the admin of the account share their API tokens with you.

An API token will give you access to every model that belongs to the admin’s account.

MatterPaks™ require a few minutes to be generated for a space. Once the unlock is requested, please allow up to 15 minutes before querying for the MatterPak™ Bundle.

To add or update rich media content, you have to use the updateMattertagMediaUrl() mutation. If you want to remove rich media content, you must use the removeMattertagMedia() mutation.

The GraphQL Schema does show that addMattertag() and patchMattertag() can update “media” and “mediaType.” However, at this time, it’s not possible to directly update these values if you’re using rich media content.