MapSet

MapSet APIs allow you to create and manage collections of maps with relative positioning for large-scale VPS coverage.

To whitelist your domain, follow: Configuring Allowed Domains (CORS)

Overview

A MapSet is a collection of two or more maps positioned relative to each other. This enables:

• Large area coverage by combining multiple scans

• Seamless localization across connected spaces

• Flexible map arrangement and positioning

Using Codes Instead of IDs

All MapSet APIs use human-readable codes:

• MapSet Code (e.g., MSET_ZIRWP1NV0WBH) - Use this for all MapSet operations

• Map Code (e.g., MAP_WUTCLWDXTK6U) - Use this when adding maps to a MapSet

You can find these codes in the MultiSet Developer Portal or from API responses.

Endpoints

Create MapSet using Overlap

Creates a new MapSet from two existing maps that share overlapping scan area — pass only the Map Codes of a source and a target map, and the cloud computes the relative pose between them automatically. No relativePose is required in the request.

When to use this: when your two scans overlap physically (e.g. you scanned a corridor twice from each end, or two adjacent rooms share a doorway). The cloud aligns the maps for you. If your maps don't overlap, use Create MapSet and supply relativePose manually instead.

Constraints:

• Both maps must be in your account and in active status.

• Neither map can already belong to a MapSet.

• The sourceMapCode becomes the origin (order=0) of the new MapSet.

Create MapSet using Overlap

post

Creates a new MapSet from two existing maps that share overlapping scan area, by passing the Map Codes of a source map and a target map. The cloud computes the relative pose between the two maps automatically — you do not need to supply a relativePose.

Both maps must already exist in your account, be in active status, and not already belong to any MapSet. The resulting MapSet uses the source map as the origin (order=0).

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Body

application/json

namestringRequired

Name of the new MapSet

Example: Building A - Floors 1 & 2

sourceMapCodestringRequired

Map Code of the source map (becomes the MapSet origin)

Example: MAP_WUTCLWDXTK6U

targetMapCodestringRequired

Map Code of the target map to align against the source

Example: MAP_7HXKP2MSNQ4Y

Responses

201

MapSet created successfully via overlap

application/json

401

Unauthorized - Invalid or expired token

403

Forbidden - One or more maps are not active or do not belong to your account

404

One or more maps not found

409

Conflict - One or more maps are already part of a MapSet

post

/map-set/overlap

HTTPcURLJavaScriptPython

POST /v1/vps/map-set/overlap HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "name": "Building A - Floors 1 & 2",
  "sourceMapCode": "MAP_WUTCLWDXTK6U",
  "targetMapCode": "MAP_7HXKP2MSNQ4Y"
}

{
  "message": "MapSet Processed successfully",
  "mapSetCode": "MSET_ZIRWP1NV0WBH"
}

---

Add Map to MapSet using Overlap

Adds a new map to an existing MapSet by overlapping it against a map that is already part of that MapSet. The cloud computes the new map's relative pose automatically from the overlap — no relativePose is required.

When to use this: when you've added a new scan that overlaps with one of the maps already in a MapSet (e.g. extending coverage to an adjacent area). If the new scan does not overlap any existing map in the set, use Add Map to MapSet and supply relativePose manually instead.

Constraints:

• sourceMapCode must already be part of the target MapSet (it acts as the anchor for overlap).

• targetMapCode must be active and not already part of any MapSet.

Add Map to MapSet using Overlap

put

Adds a new map to an existing MapSet by overlapping it against a map already inside that MapSet. The cloud computes the new map's relative pose automatically from the overlap — no relativePose required.

• sourceMapCode must be a map that is already part of the target MapSet.
• targetMapCode must be an active map in your account that is not part of any MapSet yet.
• The resulting transform is stored as the new map's relativePose within the MapSet's coordinate system.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code of the existing MapSet to extend

Example: MSET_ZIRWP1NV0WBH

Body

application/json

sourceMapCodestringRequired

Map Code of an existing map already in the MapSet (the anchor for overlap)

Example: MAP_WUTCLWDXTK6U

targetMapCodestringRequired

Map Code of the new map to add to the MapSet

Example: MAP_3HQNB7L9XP2A

Responses

200

Map added to MapSet successfully

application/json

messagestringOptionalExample: MapSet data processed successfully

401

Unauthorized - Invalid or expired token

403

Forbidden - MapSet or one of the maps is not active, or does not belong to your account

404

MapSet not found, source map not part of the MapSet, or target map not found

409

Conflict - Target map is already part of a MapSet

put

/map-set/overlap/{mapSetCode}

HTTPcURLJavaScriptPython

PUT /v1/vps/map-set/overlap/{mapSetCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "sourceMapCode": "MAP_WUTCLWDXTK6U",
  "targetMapCode": "MAP_3HQNB7L9XP2A"
}

{
  "message": "MapSet data processed successfully"
}

---

Create MapSet

Creates a new MapSet with two or more maps. Use Map Codes to reference the maps.

Create MapSet

post

Creates a new MapSet with two or more maps. Each map must include a relative pose defining its position and rotation within the MapSet.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Body

application/json

namestringRequired

Name of the MapSet

Example: Building A - Floor 1

Responses

201

MapSet created successfully

application/json

400

Bad Request - Invalid input or less than 2 maps provided

401

Unauthorized - Invalid or expired token

404

One or more maps not found

409

Conflict - One or more maps are already part of a MapSet

post

/map-set

HTTPcURLJavaScriptPython

POST /v1/vps/map-set HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 295

{
  "name": "Building A - Floor 1",
  "maps": [
    {
      "mapCode": "MAP_WUTCLWDXTK6U",
      "relativePose": {
        "position": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "rotation": {
          "qx": 0,
          "qy": 0,
          "qz": 0,
          "qw": 1
        }
      }
    },
    {
      "mapCode": "MAP_7HXKP2MSNQ4Y",
      "relativePose": {
        "position": {
          "x": 10.5,
          "y": 0,
          "z": 5.2
        },
        "rotation": {
          "qx": 0,
          "qy": 0.7071,
          "qz": 0,
          "qw": 0.7071
        }
      }
    }
  ]
}

{
  "message": "MapSet created successfully",
  "mapSetCode": "MSET_ZIRWP1NV0WBH"
}

---

Get MapSet Details

Retrieves details of a MapSet including all associated maps and their relative poses. Use the MapSet Code (e.g., MSET_ZIRWP1NV0WBH).

Get MapSet Details

get

Retrieves details of a MapSet including all associated maps and their relative poses.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Responses

200

MapSet details retrieved successfully

application/json

401

Unauthorized - Invalid or expired token

404

MapSet not found

get

/map-set/{mapSetCode}

HTTPcURLJavaScriptPython

GET /v1/vps/map-set/{mapSetCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "mapSet": {
    "name": "Building A - Floor 1",
    "mapSetCode": "MSET_ZIRWP1NV0WBH",
    "status": "active",
    "createdAt": "2026-05-30T10:48:56.146Z",
    "updatedAt": "2026-05-30T10:48:56.146Z",
    "mapSetData": [
      {
        "_id": "6756c20336a9794c6effce46",
        "order": 0,
        "relativePose": {
          "position": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "rotation": {
            "qx": 0,
            "qy": 0,
            "qz": 0,
            "qw": 1
          }
        },
        "map": {
          "mapCode": "MAP_WUTCLWDXTK6U",
          "mapName": "Lobby Area",
          "status": "active"
        }
      }
    ]
  }
}

---

Update MapSet Details

Updates the name of an existing MapSet. Use the MapSet Code.

Update MapSet Details

put

Updates the name of an existing MapSet.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Body

application/json

namestringRequired

New name for the MapSet

Example: Building A - Updated Name

Responses

200

MapSet updated successfully

application/json

messagestringOptionalExample: MapSet updated successfully

401

Unauthorized - Invalid or expired token

404

MapSet not found

put

/map-set/details/{mapSetCode}

HTTPcURLJavaScriptPython

PUT /v1/vps/map-set/details/{mapSetCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "name": "Building A - Updated Name"
}

{
  "message": "MapSet updated successfully"
}

---

Add Map to MapSet

Adds a new map to an existing MapSet with its relative pose. Use the MapSet Code in the URL and Map Code in the request body.

Add Map to MapSet

put

Adds a new map to an existing MapSet with its relative pose.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Body

application/json

mapCodestringRequired

Map Code

Example: MAP_WUTCLWDXTK6U

Responses

200

Map added to MapSet successfully

application/json

messagestringOptionalExample: MapSet data added successfully

401

Unauthorized - Invalid or expired token

404

MapSet or Map not found

put

/map-set/{mapSetCode}

HTTPcURLJavaScriptPython

PUT /v1/vps/map-set/{mapSetCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "mapCode": "MAP_9RNVK3JTPL8X",
  "relativePose": {
    "position": {
      "x": 20,
      "y": 0,
      "z": 10
    },
    "rotation": {
      "qx": 0,
      "qy": 0,
      "qz": 0,
      "qw": 1
    }
  }
}

{
  "message": "MapSet data added successfully"
}

---

Update Map Pose in MapSet

Updates the relative pose of a map within a MapSet.

Use the dataId (MapSetData ID) from the Get MapSet Details response. This is the only operation that requires an internal ID.

Update Map Pose in MapSet

put

Updates the relative pose of a map within a MapSet. Use the dataId from the MapSet details response.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

dataIdstringRequired

MapSetData ID (obtained from Get MapSet Details response)

Example: 6756c20336a9794c6effce46

Body

application/json

Responses

200

Map pose updated successfully

application/json

messagestringOptionalExample: MapSetData updated successfully

400

Invalid dataId format

401

Unauthorized - Invalid or expired token

404

MapSetData not found

put

/map-set/data/{dataId}

HTTPcURLJavaScriptPython

PUT /v1/vps/map-set/data/{dataId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "relativePose": {
    "position": {
      "x": 15,
      "y": 0,
      "z": 7.5
    },
    "rotation": {
      "qx": 0,
      "qy": 0,
      "qz": 0,
      "qw": 1
    }
  }
}

{
  "message": "MapSetData updated successfully"
}

---

Delete Map from MapSet

Removes a map from a MapSet.

Constraints:

• Cannot delete the primary map (order=0)

• Cannot delete if it would leave less than 2 maps in the MapSet

• Use the dataId from the Get MapSet Details response

Delete Map from MapSet

delete

Removes a map from a MapSet. Cannot delete the primary map (order=0) or if deletion would leave less than 2 maps in the MapSet.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

dataIdstringRequired

MapSetData ID (obtained from Get MapSet Details response)

Example: 6756c20336a9794c6effce46

Responses

200

Map removed from MapSet successfully

application/json

messagestringOptionalExample: MapSetData deleted successfully

400

Invalid dataId format

401

Unauthorized - Invalid or expired token

404

MapSetData not found

409

Cannot delete primary map or would leave less than 2 maps in MapSet

delete

/map-set/data/{dataId}

HTTPcURLJavaScriptPython

DELETE /v1/vps/map-set/data/{dataId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "MapSetData deleted successfully"
}

---

Delete MapSet

Deletes a MapSet and all associated map data entries. The maps themselves are not deleted, only their association with the MapSet. Use the MapSet Code.

Delete MapSet

delete

Deletes a MapSet and all associated map data entries. The maps themselves are not deleted, only their association with the MapSet.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Responses

200

MapSet deleted successfully

application/json

messagestringOptionalExample: MapSet and associated MapSetData deleted successfully

401

Unauthorized - Invalid or expired token

404

MapSet not found

delete

/map-set/{mapSetCode}

HTTPcURLJavaScriptPython

DELETE /v1/vps/map-set/{mapSetCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "MapSet and associated MapSetData deleted successfully"
}

Schemas

RelativePose

The relativePose object defines a map's position and orientation within the MapSet coordinate system:

Field	Type	Description
position.x	number	X position coordinate
position.y	number	Y position coordinate
position.z	number	Z position coordinate
rotation.qx	number	X component of quaternion rotation
rotation.qy	number	Y component of quaternion rotation
rotation.qz	number	Z component of quaternion rotation
rotation.qw	number	W component of quaternion rotation

The first map in a MapSet (order=0) typically uses identity pose: position (0,0,0) and rotation quaternion (0,0,0,1).