Map Version

Create, inspect, and manage Map Versions over the REST API.

These endpoints let you create a Map Version, add additional scans to it, switch which scan is active, and tear the version down. See Map Versioning for the concepts behind these calls.

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

Codes used in these APIs

• Version Code (e.g. MVER_W6NTBJ0ALVUN), identifies a Map Version. Returned when you create one.

• Map Code (e.g. MAP_BTTE1MOXYVT8), identifies an individual map. Used as the base, target, or active map.

Endpoints

Create Map Version

Creates a new Map Version. The sourceMapCode becomes the base map, its coordinate frame becomes the version's frame, and your content layer should be authored against it. The targetMapCode is added as the first additional version.

The response is 202 Accepted, the VPS computes the rigid transform asynchronously. Poll Get Map Version until the target map's status flips from computing to ready.

Constraints:

• Both maps must be in your account.

• Neither map can already belong to a Map Version.

• sourceMapCode and targetMapCode must differ.

Create Map Version

post

Creates a new Map Version from two existing maps. The sourceMapCode becomes the base map of the version (its coordinate frame is the version's coordinate frame). The targetMapCode is added as the first additional version of that map.

After this call, the VPS asynchronously computes the rigid transform that aligns the target scan to the base. While the computation runs, the target's status will move through pending then computing; once finished it becomes ready and can be activated.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Body

application/json

sourceMapCodestringRequired

Map Code of the base map (its coordinate frame becomes the version's frame).

Example: MAP_BTTE1MOXYVT8

targetMapCodestringRequired

Map Code of the new scan to align to the base map. Must differ from sourceMapCode.

Example: MAP_QQYKIBHXZE01

Responses

202

Map Version created. Transform computation is in progress.

application/json

messagestringOptionalExample: Map version created, offset computation is in progress

400

Bad Request, source and target are the same, or one of the maps is invalid.

401

Unauthorized, invalid or expired token.

403

Forbidden, one of the maps does not belong to your account.

404

One or both maps not found.

409

Conflict, one of the maps already belongs to a Map Version.

post

/map-version

HTTPcURLJavaScriptPython

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

{
  "sourceMapCode": "MAP_BTTE1MOXYVT8",
  "targetMapCode": "MAP_QQYKIBHXZE01"
}

{
  "message": "Map version created, offset computation is in progress",
  "version": {
    "versionCode": "MVER_W6NTBJ0ALVUN",
    "baseMapId": "text",
    "activeMapId": "text",
    "relativePose": {
      "position": {
        "x": 0.42,
        "y": -0.05,
        "z": 1.18
      },
      "rotation": {
        "qx": 0,
        "qy": 0.7071,
        "qz": 0,
        "qw": 0.7071
      }
    },
    "status": "active",
    "createdAt": "2026-05-13T00:51:53.744Z",
    "updatedAt": "2026-05-13T00:51:53.744Z"
  },
  "targetData": {
    "mapVersionDataId": "text",
    "targetMapId": "text",
    "relativePose": {
      "position": {
        "x": 0.42,
        "y": -0.05,
        "z": 1.18
      },
      "rotation": {
        "qx": 0,
        "qy": 0.7071,
        "qz": 0,
        "qw": 0.7071
      }
    },
    "status": "ready",
    "failureReason": "text",
    "computeJob": {},
    "isActive": true,
    "isBase": true
  }
}

Get Map Version

Returns the full state of a Map Version: every scan in it, each scan's per-map relativePose, the current active map, and processing status.

Get Map Version

get

Returns the Map Version along with all maps in the version, their per-map relative pose, and processing status.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequired

Map Version Code (e.g. MVER_W6NTBJ0ALVUN).

Example: MVER_W6NTBJ0ALVUN

Responses

200

Map Version details.

application/json

401

Unauthorized, invalid or expired token.

403

Forbidden, Map Version does not belong to your account.

404

Map Version not found.

get

/map-version/{versionCode}

HTTPcURLJavaScriptPython

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

{
  "versionCode": "MVER_W6NTBJ0ALVUN",
  "baseMapId": "text",
  "activeMapId": "text",
  "relativePose": {
    "position": {
      "x": 0.42,
      "y": -0.05,
      "z": 1.18
    },
    "rotation": {
      "qx": 0,
      "qy": 0.7071,
      "qz": 0,
      "qw": 0.7071
    }
  },
  "status": "active",
  "createdAt": "2026-05-13T00:51:53.744Z",
  "updatedAt": "2026-05-13T00:51:53.744Z",
  "maps": [
    {
      "mapVersionDataId": "text",
      "targetMapId": "text",
      "relativePose": {
        "position": {
          "x": 0.42,
          "y": -0.05,
          "z": 1.18
        },
        "rotation": {
          "qx": 0,
          "qy": 0.7071,
          "qz": 0,
          "qw": 0.7071
        }
      },
      "status": "ready",
      "failureReason": "text",
      "computeJob": {},
      "isActive": true,
      "isBase": true,
      "map": {
        "mapCode": "MAP_BTTE1MOXYVT8",
        "mapName": "Abode",
        "status": "active",
        "thumbnail": "text"
      }
    }
  ]
}

Add Map to Map Version

Adds a new scan to an existing Map Version. The transform is computed against the currently active map in the version (not the original base). This is what lets you keep adding fresh scans over time without alignment quality decaying back to the original capture.

Constraints:

• The target map must be in your account and must not already belong to a Map Version.

Add Map to Map Version

post

Adds a new map as an additional version. The source for the transform computation is the currently active map in the version, this lets you incrementally version a space without having to re-align every scan against the original base.

The map's status will move through pending then computing while the VPS computes the transform, then ready once finished.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Body

application/json

targetMapCodestringRequired

Map Code of the scan to add to the version.

Example: MAP_NEWSCANXYZ12

Responses

202

Map added to version. Transform computation is in progress.

application/json

messagestringOptionalExample: Map added to version, offset computation is in progress

401

Unauthorized, invalid or expired token.

403

Forbidden, Map Version or target map does not belong to your account.

404

Map Version or target map not found.

409

Conflict, target map already belongs to a Map Version.

post

/map-version/{versionCode}/maps

HTTPcURLJavaScriptPython

POST /v1/vps/map-version/{versionCode}/maps HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "targetMapCode": "MAP_NEWSCANXYZ12"
}

{
  "message": "Map added to version, offset computation is in progress",
  "mapVersionData": {
    "mapVersionDataId": "text",
    "targetMapId": "text",
    "relativePose": {
      "position": {
        "x": 0.42,
        "y": -0.05,
        "z": 1.18
      },
      "rotation": {
        "qx": 0,
        "qy": 0.7071,
        "qz": 0,
        "qw": 0.7071
      }
    },
    "status": "ready",
    "failureReason": "text",
    "computeJob": {},
    "isActive": true,
    "isBase": true
  }
}

Activate Map in Version

Switches which map in the version is active. After this call, VPS queries against the base map's mapCode are silently routed to the activated map, and the returned pose is transformed back into the base map's coordinate frame.

Constraints:

• The given map must already be part of this version.

• The given map must be in ready status, you cannot activate a map whose alignment is still computing or failed.

Activate Map in Version

put

Switches which map in the version is active. Subsequent VPS query calls against the base map are silently routed to the active map, and the returned pose is transformed back into the base map's coordinate frame, so the developer's content layer keeps working.

The given map must already be part of this version and must be in ready status.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Body

application/json

mapCodestringRequired

Map Code of the map to set as active. Must be in ready status.

Example: MAP_QQYKIBHXZE01

Responses

200

Active map updated.

application/json

400

Bad Request, given map is not part of this version, or is not in ready status.

401

Unauthorized, invalid or expired token.

403

Forbidden, Map Version does not belong to your account.

404

Map Version or map not found.

put

/map-version/{versionCode}/activate

HTTPcURLJavaScriptPython

PUT /v1/vps/map-version/{versionCode}/activate HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "mapCode": "MAP_QQYKIBHXZE01"
}

{
  "message": "Active map updated",
  "version": {
    "versionCode": "MVER_W6NTBJ0ALVUN",
    "baseMapId": "text",
    "activeMapId": "text",
    "relativePose": {
      "position": {
        "x": 0.42,
        "y": -0.05,
        "z": 1.18
      },
      "rotation": {
        "qx": 0,
        "qy": 0.7071,
        "qz": 0,
        "qw": 0.7071
      }
    },
    "status": "active",
    "createdAt": "2026-05-13T00:51:53.744Z",
    "updatedAt": "2026-05-13T00:51:53.744Z"
  }
}

---

Remove Map from Version

Removes a single scan from a Map Version. The map itself is not deleted, only its association with the version.

Constraints:

• You cannot remove the base map of the version.

• You cannot remove the currently active map. Activate a different map first, then remove this one.

Remove Map from Version

delete

Removes a map from the version. The map itself is not deleted, only its association with the version.

You cannot remove the base map or the currently active map. To remove either of these, activate a different map first, or delete the whole version.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

targetMapCodestringRequiredExample: MAP_QQYKIBHXZE01

Responses

200

Map removed from version.

application/json

400

Bad Request, cannot remove the base map or the active map.

401

Unauthorized, invalid or expired token.

403

Forbidden, Map Version does not belong to your account.

404

Map Version not found, or map is not part of this version.

delete

/map-version/{versionCode}/maps/{targetMapCode}

HTTPcURLJavaScriptPython

DELETE /v1/vps/map-version/{versionCode}/maps/{targetMapCode} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Map removed from version",
  "deleted": true
}

---

Delete Map Version

Deletes the Map Version and clears the version association from every map in it. The maps themselves are kept.

Delete Map Version

delete

Deletes the Map Version and removes the version pointer from every map in it. The maps themselves are not deleted.

Authorizations

bearerAuth

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Responses

200

Map Version deleted.

application/json

401

Unauthorized, invalid or expired token.

403

Forbidden, Map Version does not belong to your account.

404

Map Version not found.

delete

/map-version/{versionCode}

HTTPcURLJavaScriptPython

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

{
  "message": "Map version deleted",
  "deleted": true
}

Status values

Status	Meaning
computing	VPS is computing the transform between this scan and the version's source map.
ready	Transform is computed. The map can be set as active.
failed	The VPS could not align this scan. Inspect failureReason on the Get Map Version response.