Ctrlk
Developer PortalDemosGithub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MapSet

Create, read, update and delete MapSets, add maps with or without overlap, and set the pose of a map inside a set.

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

Every relativePose you send must be in the left-handed, Y-up (LHS / Unity) coordinate system, the map's native frame and the one a localization query returns when isRightHanded is omitted. Positions are in meters. There is no isRightHanded flag on the MapSet endpoints, so if your poses come from a right-handed tool (ARKit, ARCore, Three.js, ROS), convert them to LHS before sending. See RelativePose below.

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. Poses are in the map's native left-handed, Y-up (LHS / Unity) coordinate system, positions in meters. Convert right-handed poses to LHS before sending.

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
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). Returned poses are in the same left-handed, Y-up frame you supply them in, see RelativePose.

Get MapSet Details

get

Retrieves details of a MapSet including all associated maps and their relative poses. Poses are returned in the left-handed, Y-up (LHS / Unity) coordinate system.

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
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
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. The relativePose must be left-handed, Y-up (Unity), see RelativePose.

Add Map to MapSet

put

Adds a new map to an existing MapSet with its relative pose. The pose must be in the left-handed, Y-up (LHS / Unity) coordinate system, positions in meters.

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
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. The new relativePose must be left-handed, Y-up (Unity), see RelativePose.

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. The pose must be in the left-handed, Y-up (LHS / Unity) coordinate system, positions in meters.

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
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
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
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. It is the transform that moves the map's local frame into the MapSet frame, which is the frame of the origin map (order=0).

Coordinate frame: left-handed, Y-up (LHS / Unity). This is the map's native frame, the same one the position and rotation of a localization response use when isRightHanded is false or omitted. The MapSet endpoints accept and return poses in this frame only; there is no isRightHanded switch. If your alignment was computed in a right-handed tool (ARKit, ARCore, Three.js, ROS), convert to LHS first: negate x on the position and negate qy and qz on the quaternion. If your data is right-handed Z-up (ROS, most laser scanners), swap the Y and Z axes instead of negating X: the swap alone flips handedness and makes Y the up axis. See Coordinate Systems.

Field
Type
Description

position.x

number

X offset in meters, left-handed Y-up frame

position.y

number

Y offset in meters (up)

position.z

number

Z offset in meters

rotation.qx

number

X component of the unit quaternion

rotation.qy

number

Y component of the unit quaternion

rotation.qz

number

Z component of the unit quaternion

rotation.qw

number

W (scalar) component of the unit quaternion

The first map in a MapSet (order=0) typically uses identity pose: position (0,0,0) and rotation quaternion (0,0,0,1). Poses computed by the overlap endpoints or adjusted in the Developer Portal or the Unity MapSet Alignment scene are already in this frame and can be read back from Get MapSet Details as is.

PreviousMap Operations
NextMap Upload

Last updated

Was this helpful?