> For the complete documentation index, see [llms.txt](https://multiset.gitbook.io/multiset/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiset.gitbook.io/multiset/basics/rest-api-docs/mapset.md). # MapSet 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)](/multiset/basics/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-1cf20901e17fdda75b38191ef8bdc6e40611d603%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### Add Map to MapSet using Overlap Adds a new map to an existing MapSet by overlapping it against a map that is already part of that MapSet. The cloud computes the new map's relative pose automatically from the overlap — no `relativePose` is required. {% hint style="info" %} **When to use this:** when you've added a new scan that overlaps with one of the maps already in a MapSet (e.g. extending coverage to an adjacent area). If the new scan does not overlap any existing map in the set, use [Add Map to MapSet](#add-map-to-mapset) and supply `relativePose` manually instead. {% endhint %} **Constraints:** * `sourceMapCode` must already be part of the target MapSet (it acts as the anchor for overlap). * `targetMapCode` must be `active` and not already part of any MapSet. {% 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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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. {% 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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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`). {% 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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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. {% 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-1cf20901e17fdda75b38191ef8bdc6e40611d603%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} *** ### Update Map Pose in MapSet Updates the relative pose of a map within a MapSet. {% 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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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-1cf20901e17fdda75b38191ef8bdc6e40611d603%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-1cf20901e17fdda75b38191ef8bdc6e40611d603%2Fmapset-crud-api.yaml?alt=media) {% endopenapi %} ## 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 | {% 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). {% 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://multiset.gitbook.io/multiset/basics/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.