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, control which scans are active for querying, 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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Body

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

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-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "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,
    "hasPano": false
  }
}

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

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

versionCodestringOptionalExample: MVER_W6NTBJ0ALVUN

baseMapIdstringOptional

Internal ID of the base map. The version's coordinate frame is the base map's frame.

activeMapIdstringOptional

Internal ID of the currently active map. Query traffic against the base map is routed here.

statusstringOptionalExample: active

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

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}

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-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "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,
      "hasPano": false,
      "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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Body

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

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,
    "hasPano": false
  }
}

Activate Maps in Version

Sets which map(s) in the version are active (the "query-active" set). After this call, VPS queries against the base map's mapCode are localized against every active map in the version, and each returned pose is transformed back into the base map's coordinate frame, so your content layer keeps working.

You can activate a single map or multiple maps at once by providing exactly one of:

mapCode: a single Map Code, or
mapCodes: an array of Map Codes (the full active set).

This call replaces the active set: any map in the version that isn't listed is deactivated. This is the same control as the Query Active toggle in the Developer Portal. See Map Versioning.

Constraints:

Every listed map must already be part of this version.
Every listed map must be in ready status. You cannot activate a map whose alignment is still computing or failed.
At least one map must remain active.

Sample Request (activate multiple maps)

{
    "mapCodes": ["MAP_BTTE1MOXYVT8", "MAP_QQYKIBHXZE01"]
}

To activate just one map, send { "mapCode": "MAP_QQYKIBHXZE01" } instead.

Activate Maps in Version

put

Sets which map(s) in the version are active (the "query-active" set). Subsequent VPS query calls against the base map are localized against every active map, and the returned pose is transformed back into the base map's coordinate frame, so the developer's content layer keeps working.

Provide exactly one of:

mapCode — activate a single map, or
mapCodes — activate multiple maps at once.

This call replaces the active set: any map not listed is deactivated. Every listed map must already be part of this version and be in ready status. (This is the same control as the Query Active toggle in the Developer Portal.)

Authorizations

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Body

Provide exactly one of mapCode or mapCodes.

mapCodestringOptional

Activate a single map. Must be in ready status. Provide this or mapCodes, not both.

Example: MAP_QQYKIBHXZE01

mapCodesstring[] · min: 1Optional

Activate multiple maps at once. All must be in ready status. Provide this or mapCode, not both.

Example: ["MAP_BTTE1MOXYVT8","MAP_QQYKIBHXZE01"]

Responses

200

Active map updated.

application/json

messagestringOptionalExample: Active map updated

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

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-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

targetMapCodestringRequiredExample: MAP_QQYKIBHXZE01

Responses

200

Map removed from version.

application/json

messagestringOptionalExample: Map removed from version

deletedbooleanOptionalExample: true

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}

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

AuthorizationstringRequired

JWT token obtained from the authentication endpoint.

Path parameters

versionCodestringRequiredExample: MVER_W6NTBJ0ALVUN

Responses

200

Map Version deleted.

application/json

messagestringOptionalExample: Map version deleted

deletedbooleanOptionalExample: true

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}

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.

PreviousObject Tracking REST API

NextSimulation Data

Last updated 1 month ago

Was this helpful?