MultiSet
Developer PortalContact UsTutorials
  • MultiSet Developer Docs
  • Getting Started
    • Changelog
    • MultiSet Unity SDK
      • Universal 3D (Core) support
    • FAQ
  • Basics
    • Maps
      • Mapping Instruction
      • Mapping Planning
      • Mapping Equipment
    • MapSet : Multiple Maps
      • Merging Maps without Overlap
        • Extend a MapSet
      • Merging Maps with Overlap
      • Adjust Map Transformation
    • ModelSet: Object Anchoring
      • How to Create a ModelSet
    • App Localization
    • Credentials
    • Analytics and Usage
    • Downloads
    • REST API Docs
    • WebXR Integration
    • Third Party Scans
      • Matterport
      • Leica Scans
    • MapFoundry
    • Georeferencing Maps
      • How to Align Scans
      • Outdoor-Indoor Transitions with Multiset
    • On-Premises Localization
    • Support
  • Unity-SDK
    • Authentication
    • Sample Scenes
      • Localization
      • Single Frame Localization
      • ModelSet Tracking
      • Navigation
      • Training
    • On-Cloud Localization
      • Individual Map
      • MapSet (Multiple maps)
        • Hint MapCodes
      • Pose Prior : HintPosition
      • GeoHint in Localization
    • Occlusion
    • NavMesh Navigation
    • Multiplayer AR
    • Building Steps
    • API Reference
      • MultisetSdkManager
      • MapLocalizationManager
      • SingleFrameLocalizationManager
      • ModelSetTrackingManager
      • MapMeshHandler
      • ToastManager
  • MultiSet-Quest-SDK
    • Installation Guide
    • Map Mesh Downloader
    • Authentication
    • Sample Scenes
      • Single Frame Localization
  • Native Support
    • iOS Native
    • Android Native
  • MultiSet App
    • Content Space
Powered by GitBook
On this page
  1. Basics

REST API Docs

PreviousDownloadsNextWebXR Integration

Last updated 21 days ago

Was this helpful?

CtrlK
  • M2M Auth
  • POSTGenerate a token for an M2M client
  • GET All VPS maps for an account
  • GETGet all VPS maps
  • DELETEDelete a VPS map by ID
  • VPS Query API
  • POSTQuery a VPS map with specific parameters
  • VPS Query Form API
  • POSTQuery a VPS map or mapset using form-data
  • VPS Multi Image Query API
  • POSTMulti-image query for a VPS map or map set
  • ModelSet Query API
  • POSTModelSet Query API
  • File download API
  • GETRetrieve a pre-signed S3 URL for file download
  • APIs to Get MapSet (merged maps)
  • GETGet paginated list of MapSets
  • GETRetrieve a Map Set by ID
  • GETGet a paginated list of VPS objects

Was this helpful?

You can use our REST API to fetch and query your VPS Maps to get device Pose with respect to Map local origin, the query API takes query image (encoded as a base64 string) and other image metadata.

Note: you will need to contact MultiSet Team before using this api's to approve your domain and avoid CORS issue

M2M Auth

Generate a token for an M2M client

post

Authenticates a machine-to-machine client using Basic Authentication and returns an access token. The Basic Auth value should be constructed as: Base64(clientId:clientSecret)

Authorizations
Header parameters
UsernamestringRequired

Client ID for authentication

PasswordstringRequired

Client Secret for authentication

AuthorizationstringRequired

Basic authentication header. Format: "Basic " + Base64(clientId:clientSecret)

Example: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Body
stringOptional
Responses
200

Token generated successfully

application/json
400

Bad request

application/json
401

Unauthorized

application/json
403

Forbidden

application/json
post
POST /v1/m2m/token HTTP/1.1
Host: api.multiset.ai
Authorization: text
Username: text
Password: text
Content-Type: text/plain
Accept: */*
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cC.......",
  "expiresOn": "2024-10-22T18:40:54.908Z"
}

GET All VPS maps for an account

Get all VPS maps

get

Retrieves a paginated list of VPS maps using limit and page parameters

Authorizations
Query parameters
limitinteger · min: 1 · max: 100Optional

Number of items to return per page

Default: 10Example: 10
pageinteger · min: 1Optional

Page number for pagination

Default: 1Example: 1
Responses
200

VPS maps retrieved successfully

application/json
401

Unauthorized

application/json
get
GET /v1/vps/map HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
  "data": [
    {
      "id": "66ca3f3b773b18f09e131279",
      "name": "Office Building Map",
      "description": "3D map of the main office building",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "status": "active"
    }
  ],
  "pagination": {
    "totalItems": 45,
    "totalPages": 5,
    "currentPage": 1,
    "itemsPerPage": 10
  }
}

Delete a VPS map by ID

delete

Permanently deletes a VPS map identified by its unique ID

Authorizations
Path parameters
mapIdstringRequired

The unique ID of the VPS map to delete

Example: 66ca3f3b773b18f09e131279
Responses
204

VPS map deleted successfully

400

Bad Request - Invalid map ID format

application/json
401

Unauthorized

application/json
404

Map not found

application/json
500

Internal Server Error - Something went wrong on the server

application/json
delete
DELETE /v1/vps/map/{mapId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*

No content

VPS Query API

Query your map to get the device position with respect to Map local origin, the query API takes query image (encoded as base64 string) and other image metadata

Query a VPS map with specific parameters

post
Authorizations
Body
mapCodestringOptional

Unique identifier for the VPS map

Example: MAP-X2P23E7Q35VD
isRightHandedbooleanOptional

Flag to indicate if response pose is in right-handed coordinate system

Example: false
queryImagestring · base64Required

Base64 encoded image data

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh
Responses
200

Query successful

application/json
400

Bad request

application/json
401

Unauthorized

application/json
post
POST /v1/vps/map/query HTTP/1.1
Host: api.mulitset.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 388

{
  "mapCode": "MAP-X2P23E7Q35VD",
  "cameraIntrinsics": {
    "fx": 664.3856201171875,
    "fy": 664.3856201171875,
    "px": 478.9782409667969,
    "py": 364.9932861328125
  },
  "isRightHanded": false,
  "resolution": {
    "width": 960,
    "height": 720
  },
  "queryImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh"
}
{
  "poseFound": true,
  "position": {
    "x": 2.482360321597187,
    "y": 0.11936171927197065,
    "z": 8.06609995252609
  },
  "rotation": {
    "x": 0.02949315565629783,
    "y": 0.7673793569590026,
    "z": -0.01740867960782986,
    "w": 0.6402780756491143
  },
  "confidence": 0.459232334365416
}

VPS Query Form API

Query a VPS map or mapset using form-data

post
Authorizations
Body
mapCodestringOptional

The map code for the map to query (required if mapSetCode is not provided)

mapSetCodestringOptional

The map set code for the map set to query (required if mapCode is not provided)

isRightHandedstring · enumOptionalExample: truePossible values:
fxstringRequiredExample: 669.535888671875
fystringRequiredExample: 669.535888671875
pxstringRequiredExample: 478.8777160644531
pystringRequiredExample: 364.9244079589844
widthstringRequiredExample: 960
heightstringRequiredExample: 720
queryImagestring · binaryRequired

Image file for multipart requests

Responses
200

Query successful

application/json
Responseobject

Successful query response (structure to be defined)

400

Bad request

application/json
401

Unauthorized

application/json
post
POST /v1/vps/map/query-form HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 210

{
  "mapCode": "text",
  "mapSetCode": "text",
  "isRightHanded": "true",
  "fx": "669.535888671875",
  "fy": "669.535888671875",
  "px": "478.8777160644531",
  "py": "364.9244079589844",
  "width": "960",
  "height": "720",
  "queryImage": "binary"
}
{}

VPS Multi Image Query API

Multi-image query for a VPS map or map set

post

Performs a query using one or more uploaded images, along with camera intrinsics and optional map or map-set identifiers. Supports up to four images in a single request.

Authorizations
Body
isRightHandedstring · enumOptional

Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string ("true" or "false").

Example: truePossible values:
widthstringRequired

The width (in pixels) of the input image(s).

Example: 960
heightstringRequired

The height (in pixels) of the input image(s).

Example: 720
pxstringRequired

The principal point x-coordinate.

Example: 478.838623046875
pystringRequired

The principal point y-coordinate.

Example: 365.346618652343
fxstringRequired

The focal length along x-axis.

Example: 670.4620971679688
fystringRequired

The focal length along y-axis.

Example: 670.4620971679688
mapIdstringOptional

ID of the specific map.

mapCodestringOptional

Code to identify the map.

mapSetIdstringOptional

A unique ID for the map set.

mapSetCodestringOptional

A code to identify the map set.

image1string · binaryRequired

The first image file to be uploaded.

image1_datastringOptional

JSON-encoded metadata for image1 (e.g., position and rotation).

Example: {"x":-5.1772,"y":0.2936,"z":-2.6439,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}
image2string · binaryOptional

The second image file to be uploaded.

image2_datastringOptional

JSON-encoded metadata for image2.

Example: {"x":-3.12,"y":1.01,"z":2.56,"qx":0.0,"qy":0.707,"qz":0.0,"qw":0.707}
image3string · binaryOptional

The third image file to be uploaded.

image3_datastringOptional

JSON-encoded metadata for image3.

Example: {"x":1.23,"y":-0.56,"z":5.0,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}
image4string · binaryOptional

The fourth image file to be uploaded.

image4_datastringOptional

JSON-encoded metadata for image4.

Example: {"x":10.0,"y":-2.0,"z":0.0,"qx":0.0,"qy":1.0,"qz":0.0,"qw":0.0}
Responses
200

Query successful

application/json
400

Bad request

application/json
401

Unauthorized - Missing or invalid token

application/json
404

Map/MapSet not found (if applicable)

application/json
500

Internal server error

application/json
post
POST /v1/vps/map/multi-image-query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 697

{
  "isRightHanded": "true",
  "width": "960",
  "height": "720",
  "px": "478.838623046875",
  "py": "365.346618652343",
  "fx": "670.4620971679688",
  "fy": "670.4620971679688",
  "mapId": "",
  "mapCode": "",
  "mapSetId": "",
  "mapSetCode": "",
  "image1": "binary",
  "image1_data": "{\"x\":-5.1772,\"y\":0.2936,\"z\":-2.6439,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
  "image2": "binary",
  "image2_data": "{\"x\":-3.12,\"y\":1.01,\"z\":2.56,\"qx\":0.0,\"qy\":0.707,\"qz\":0.0,\"qw\":0.707}",
  "image3": "binary",
  "image3_data": "{\"x\":1.23,\"y\":-0.56,\"z\":5.0,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
  "image4": "binary",
  "image4_data": "{\"x\":10.0,\"y\":-2.0,\"z\":0.0,\"qx\":0.0,\"qy\":1.0,\"qz\":0.0,\"qw\":0.0}"
}
{
  "success": true,
  "location": {
    "position": {
      "x": -5.1772,
      "y": 0.2936,
      "z": -2.6439
    },
    "rotation": {
      "qx": -0.0185,
      "qy": 0.9949,
      "qz": -0.0691,
      "qw": 0.0703
    }
  },
  "confidence": 0.89,
  "mapId": "66ca3f3b773b18f09e131279"
}

ModelSet Query API

ModelSet Query API

post

Query a VPS object using an uploaded image and camera parameters. Accepts objectCode to identify the target object, and returns the query result from the external API.

Authorizations
Body
objectCodestringRequired

The code of the VPS object

Example: OBJ-001
fxstringRequired

Camera intrinsic parameter fx (focal length x-axis)

Example: 1000.0
fystringRequired

Camera intrinsic parameter fy (focal length y-axis)

Example: 1000.0
pxstringRequired

Camera intrinsic parameter px (principal point x-coordinate)

Example: 640.0
pystringRequired

Camera intrinsic parameter py (principal point y-coordinate)

Example: 480.0
isRightHandedstring · enumRequired

Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string ("true" or "false").

Example: truePossible values:
widthstringRequired

The width (in pixels) of the input image

Example: 1280
heightstringRequired

The height (in pixels) of the input image

Example: 720
queryImagestring · binaryRequired

The image file to query against the object

Responses
200

Query successful

application/json
400

Bad request - Invalid parameters or missing required fields

application/json
401

Unauthorized - Missing or invalid token

application/json
403

Forbidden - Access denied

application/json
404

Object not found

application/json
500

Internal server error

application/json
post
POST /v1/vps/object/query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 153

{
  "objectCode": "OBJ-001",
  "fx": "1000.0",
  "fy": "1000.0",
  "px": "640.0",
  "py": "480.0",
  "isRightHanded": "true",
  "width": "1280",
  "height": "720",
  "queryImage": "binary"
}
{
  "success": true,
  "result": {
    "position": {
      "x": 2.1234,
      "y": 1.5678,
      "z": 0.9876
    },
    "rotation": {
      "qx": 0.0123,
      "qy": 0.4567,
      "qz": 0.0789,
      "qw": 0.8901
    },
    "confidence": 0.92
  },
  "message": "Query successful."
}

File download API

Retrieve a pre-signed S3 URL for file download

get

Generates a temporary, pre-signed URL for downloading a file from S3

Authorizations
Query parameters
keystringRequired

Unique identifier for the file

Example: 671b454e33d6dc761ca15156/6756c20336a9794c6effce42/Mesh/TexturedMesh.glb
Responses
200

Successfully generated pre-signed URL

application/json
401

Unauthorized - Invalid or expired token

404

File not found

500

Server error

get
GET /v1/file HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
  "url": "https://amazonaws.com/671bX-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=%2Faws4_request&X-Amz-Date=20241658753a8c6380ad6d01c217e1ad978d88e2ba6a4&X-Amz-SignedHeaders=host&x-id=GetObject"
}

APIs to Get MapSet (merged maps)

Get the list of all Mapsets in an account

Get paginated list of MapSets

get

Retrieves a paginated list of MapSets associated with the authenticated user's account

Authorizations
Query parameters
limitinteger · min: 1 · max: 100Optional

Number of items to return per page

Default: 10Example: 10
pageinteger · min: 1Optional

Page number for pagination

Default: 1Example: 1
Responses
200

MapSets retrieved successfully

application/json
400

Bad Request - Invalid parameters

application/json
401

Unauthorized

application/json
500

Internal Server Error - Something went wrong on the server

application/json
get
GET /v1/vps/map-set HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
  "data": [
    {
      "id": "66ca3f3b773b18f09e131280",
      "name": "Office Buildings Collection",
      "description": "Collection of office building maps",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "status": "active",
      "mapCount": 3
    }
  ],
  "pagination": {
    "totalItems": 12,
    "totalPages": 2,
    "currentPage": 1,
    "itemsPerPage": 10
  }
}

Get details of all maps of a specific Mapset using MapSetID

Retrieve a Map Set by ID

get

Fetches details of a specific map set using its unique ID.

Authorizations
Path parameters
mapSetIdstringRequired

The unique ID of the map set.

Example: 67a5c7fca18f6052c5b21653
Responses
200

Map set details retrieved successfully

application/json
400

Invalid map set ID

application/json
401

Unauthorized - Authorization header missing or invalid

application/json
404

Map set not found

application/json
500

Internal server error

application/json
get
GET /v1/vps/map-set/{mapSetId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
  "mapSet": {
    "_id": "67a5c7fca18f6052c5b21653",
    "name": "purva test new 141",
    "accountId": "67192b1b65071c55d950d11f",
    "mapSetCode": "MSET_7J7SUEFVMSV1",
    "status": "active",
    "messages": [],
    "createdAt": "2025-02-07T08:44:44.607Z",
    "updatedAt": "2025-02-07T08:44:44.607Z",
    "mapSetData": [
      {
        "_id": "67a5c7fc58eda5c8bfaedc2e",
        "createdAt": "2025-02-07T08:44:44.614Z",
        "order": 0,
        "relativePose": {
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "rotation": {
            "qx": 0,
            "qy": 0,
            "qz": 0,
            "qw": 1
          }
        },
        "updatedAt": "2025-02-07T08:44:44.614Z",
        "map": {
          "_id": "67a4a02ba18f6052c5b20833",
          "accountId": "67192b1b65071c55d950d11f",
          "mapName": "141",
          "status": "active",
          "storage": 66.59728527069092,
          "mapCode": "MAP_XCQWQYKZ26U2",
          "createdAt": "2025-02-06T11:42:35.504Z",
          "updatedAt": "2025-02-07T08:44:44.620Z",
          "mapMesh": {
            "rawMesh": {
              "type": "glb",
              "meshLink": "67192b150d11f/67a4a02b5b20833/Mesh/Mesh.glb"
            },
            "texturedMesh": {
              "type": "glb",
              "meshLink": "67192b1b6d11f/67a4a02ba2c5b20833/Mesh/TexturedMesh.glb"
            }
          },
          "thumbnail": "67192b10d11f/67a4a022c833/RGB/Rgb_20250206114139457.jpg",
          "coordinates": {
            "latitude": 22.89059543609619,
            "longitude": 57.63724517822266,
            "altitude": 901.3638305664062
          }
        }
      }
    ]
  }
}

Get a paginated list of VPS objects

get

Retrieves a paginated list of VPS objects. You can use query parameters to filter or search objects by name, and control pagination settings.

Authorizations
Query parameters
pageinteger · min: 1Optional

The page number for pagination (starting from 1)

Default: 1Example: 1
limitinteger · min: 1 · max: 100Optional

Number of records per page (maximum 100)

Default: 10Example: 10
querystring · max: 255Optional

Filter or search text for partial match on object names

Example: Multiset
Responses
200

A paginated list of VPS objects retrieved successfully

application/json
400

Bad request - Invalid query parameters

application/json
401

Unauthorized - Missing or invalid token

application/json
500

Internal server error

application/json
get
GET /v1/vps/object HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
  "data": [
    {
      "_id": "67a5b08736cb3f76aaf3a416",
      "objectName": "Multiset Object 1",
      "trackingType": "side",
      "source": {
        "provider": "web",
        "fileType": "glb",
        "coordinateSystem": "RHS"
      }
    },
    {
      "_id": "67a5b08736cb3f76aaf3a417",
      "objectName": "Multiset Object 2",
      "trackingType": "top",
      "source": {
        "provider": "mobile",
        "fileType": "obj",
        "coordinateSystem": "LHS"
      }
    }
  ],
  "currentPage": 1,
  "totalPages": 5,
  "totalCount": 42
}