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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Body

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

isGravityAlignedbooleanOptional

Set to true when both maps are already gravity aligned (+Y up). The overlap job then constrains the relative pose to a yaw-only rotation about Y, dropping roll and pitch while keeping the full X/Y/Z translation. Optional, defaults to false.

Default: falseExample: true

Responses

201

MapSet created successfully via overlap

application/json

messagestringOptionalExample: MapSet Processed successfully

mapSetCodestringOptional

Unique code for the new MapSet

Example: MSET_ZIRWP1NV0WBH

400

Bad request. Returned when a required field is missing, when the body contains a field that is not allowed, or when the two maps are on different generations.

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

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: 130

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

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

Add Map to MapSet using Overlap

Adds a new map to an existing MapSet. The new map is aligned against the entire MapSet, so you do not pick an overlapping map to anchor it against: send only the new map's Map Code. The cloud computes its relativePose automatically from the overlap, no relativePose is required, and the existing maps in the set are not affected.

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

Constraints:

targetMapCode must be active and not already part of any MapSet.
The new map must be on the same generation as the MapSet. Mixing generations returns 400.

The request body accepts only targetMapCode plus the optional isGravityAligned. Sending sourceMapCode returns 400 with {"error": "\"sourceMapCode\" is not allowed"}. An anchor map was required by an earlier version of this endpoint and is no longer accepted.

Add Map to MapSet using Overlap

put

Adds a new map to an existing MapSet. The new map is aligned against the whole MapSet, so you do not pick an overlapping anchor map: send only the new map's Map Code. The cloud computes its relativePose automatically from the overlap, and existing maps in the set are not affected.

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.
The request body accepts only targetMapCode and the optional isGravityAligned. Any other field, including sourceMapCode, is rejected with 400 and an error such as "sourceMapCode" is not allowed.

Authorizations

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code of the existing MapSet to extend

Example: MSET_ZIRWP1NV0WBH

Body

targetMapCodestringRequired

Map Code of the new map to add to the MapSet

Example: MAP_3HQNB7L9XP2A

isGravityAlignedbooleanOptional

Set to true when both the MapSet and the new map are already gravity aligned (+Y up). The overlap job then constrains the relative pose to a yaw-only rotation about Y, dropping roll and pitch while keeping the full X/Y/Z translation. Optional, defaults to false.

Default: falseExample: true

Responses

200

Map added to MapSet successfully

application/json

messagestringOptionalExample: MapSet data processed successfully

400

Bad request. Returned when the body contains a field that is not allowed (for example sourceMapCode), when targetMapCode is missing, or when the new map is on a different generation than the MapSet.

application/json

401

Unauthorized - Invalid or expired token

403

Forbidden - MapSet or the target map is not active, or does not belong to your account

404

MapSet not found, or target map not found

409

Conflict - Target map is already part of a MapSet

put/map-set/overlap/{mapSetCode}

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: 60

{
  "targetMapCode": "MAP_3HQNB7L9XP2A",
  "isGravityAligned": true
}

{
  "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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Body

namestringRequired

Name of the MapSet

Example: Building A - Floor 1

Responses

201

MapSet created successfully

application/json

messagestringOptionalExample: MapSet created successfully

mapSetCodestringOptional

Unique code for the MapSet

Example: MSET_ZIRWP1NV0WBH

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

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

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}

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-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "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",
          "hasPano": false
        },
        "baseMap": {
          "mapCode": "MAP_BTTE1MOXYVT8",
          "mapName": "Lobby Area (base)",
          "status": "active",
          "hasPano": false
        },
        "versionCode": "MVER_W6NTBJ0ALVUN"
      }
    ]
  }
}

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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Body

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}

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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

mapSetCodestringRequired

MapSet Code

Example: MSET_ZIRWP1NV0WBH

Body

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}

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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint

Path parameters

dataIdstringRequired

MapSetData ID (obtained from Get MapSet Details response)

Example: 6756c20336a9794c6effce46

Body

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}

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

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}

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

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}

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).

PreviousMap Operations

NextMap Upload

Last updated 18 days ago

Was this helpful?