> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/fundamentals/rest-api-docs/mapset.md). # 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. {% hint style="warning" %} To whitelist your domain, follow: [Configuring Allowed Domains (CORS)](/fundamentals/credentials/configuring-allowed-domains-cors.md) {% endhint %} ## 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 {% hint style="info" %} **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. {% endhint %} ## 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. {% hint style="info" %} **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](#create-mapset) and supply `relativePose` manually instead. {% endhint %} **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. {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/overlap" method="post" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### 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. {% hint style="info" %} **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](#add-map-to-mapset) and supply `relativePose` manually instead. {% endhint %} **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`. {% hint style="warning" %} 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. {% endhint %} {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/overlap/{mapSetCode}" method="put" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### Create MapSet Creates a new MapSet with two or more maps. Use **Map Codes** to reference the maps. {% hint style="warning" %} 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](#relativepose) below. {% endhint %} {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set" method="post" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### 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](#relativepose). {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/{mapSetCode}" method="get" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### Update MapSet Details Updates the name of an existing MapSet. Use the **MapSet Code**. {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/details/{mapSetCode}" method="put" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### 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](#relativepose). {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/{mapSetCode}" method="put" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### 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](#relativepose). {% hint style="info" %} Use the `dataId` (MapSetData ID) from the **Get MapSet Details** response. This is the only operation that requires an internal ID. {% endhint %} {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/data/{dataId}" method="put" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### Delete Map from MapSet Removes a map from a MapSet. {% hint style="warning" %} **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 {% endhint %} {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/data/{dataId}" method="delete" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### 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**. {% openapi src="/files/c8XCzdnLgXIkClBQrXdX" path="/map-set/{mapSetCode}" method="delete" %} [mapset-crud-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-dcfba6dbbeeee912a59d2f9e5a8095116876aed3%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} ## 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](/fundamentals/localization/coordinate-systems.md). | 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 | {% hint style="info" %} 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](/unity-sdk/ar-foundation/sample-scenes/mapset-alignment.md) scene are already in this frame and can be read back from **Get MapSet Details** as is. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.multiset.ai/fundamentals/rest-api-docs/mapset.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.