REST API Docs
Last updated
Was this helpful?
Last updated
Was this helpful?
Was this helpful?
You can use our REST API to fetch and query your VPS Maps to get device Pose with respect to Map local origin, the query API takes query image (encoded as a base64 string) and other image metadata.
Note: you will need to contact MultiSet Team before using this api's to approve your domain and avoid CORS issue
Authenticates a machine-to-machine client using Basic Authentication and returns an access token. The Basic Auth value should be constructed as: Base64(clientId:clientSecret)
Client ID for authentication
Client Secret for authentication
Basic authentication header. Format: "Basic " + Base64(clientId:clientSecret)
Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Token generated successfully
Bad request
Unauthorized
Forbidden
POST /v1/m2m/token HTTP/1.1
Host: api.multiset.ai
Authorization: text
Username: text
Password: text
Content-Type: text/plain
Accept: */*
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cC.......",
"expiresOn": "2024-10-22T18:40:54.908Z"
}
Retrieves a paginated list of VPS maps using limit and page parameters
Number of items to return per page
10
Example: 10
Page number for pagination
1
Example: 1
VPS maps retrieved successfully
Unauthorized
GET /v1/vps/map HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
"data": [
{
"id": "66ca3f3b773b18f09e131279",
"name": "Office Building Map",
"description": "3D map of the main office building",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"status": "active"
}
],
"pagination": {
"totalItems": 45,
"totalPages": 5,
"currentPage": 1,
"itemsPerPage": 10
}
}
Permanently deletes a VPS map identified by its unique ID
The unique ID of the VPS map to delete
66ca3f3b773b18f09e131279
VPS map deleted successfully
Bad Request - Invalid map ID format
Unauthorized
Map not found
Internal Server Error - Something went wrong on the server
DELETE /v1/vps/map/{mapId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
No content
Query your map to get the device position with respect to Map local origin, the query API takes query image (encoded as base64 string) and other image metadata
Unique identifier for the VPS map
MAP-X2P23E7Q35VD
Flag to indicate if response pose is in right-handed coordinate system
false
Base64 encoded image data
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh
Query successful
Bad request
Unauthorized
POST /v1/vps/map/query HTTP/1.1
Host: api.mulitset.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 388
{
"mapCode": "MAP-X2P23E7Q35VD",
"cameraIntrinsics": {
"fx": 664.3856201171875,
"fy": 664.3856201171875,
"px": 478.9782409667969,
"py": 364.9932861328125
},
"isRightHanded": false,
"resolution": {
"width": 960,
"height": 720
},
"queryImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh"
}
{
"poseFound": true,
"position": {
"x": 2.482360321597187,
"y": 0.11936171927197065,
"z": 8.06609995252609
},
"rotation": {
"x": 0.02949315565629783,
"y": 0.7673793569590026,
"z": -0.01740867960782986,
"w": 0.6402780756491143
},
"confidence": 0.459232334365416
}
The map code for the map to query (required if mapSetCode is not provided)
The map set code for the map set to query (required if mapCode is not provided)
true
Possible values: 669.535888671875
669.535888671875
478.8777160644531
364.9244079589844
960
720
Image file for multipart requests
Query successful
Successful query response (structure to be defined)
Bad request
Unauthorized
POST /v1/vps/map/query-form HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 210
{
"mapCode": "text",
"mapSetCode": "text",
"isRightHanded": "true",
"fx": "669.535888671875",
"fy": "669.535888671875",
"px": "478.8777160644531",
"py": "364.9244079589844",
"width": "960",
"height": "720",
"queryImage": "binary"
}
{}
Performs a query using one or more uploaded images, along with camera intrinsics and optional map or map-set identifiers. Supports up to four images in a single request.
Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string ("true" or "false").
true
Possible values: The width (in pixels) of the input image(s).
960
The height (in pixels) of the input image(s).
720
The principal point x-coordinate.
478.838623046875
The principal point y-coordinate.
365.346618652343
The focal length along x-axis.
670.4620971679688
The focal length along y-axis.
670.4620971679688
ID of the specific map.
Code to identify the map.
A unique ID for the map set.
A code to identify the map set.
The first image file to be uploaded.
JSON-encoded metadata for image1 (e.g., position and rotation).
{"x":-5.1772,"y":0.2936,"z":-2.6439,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}
The second image file to be uploaded.
JSON-encoded metadata for image2.
{"x":-3.12,"y":1.01,"z":2.56,"qx":0.0,"qy":0.707,"qz":0.0,"qw":0.707}
The third image file to be uploaded.
JSON-encoded metadata for image3.
{"x":1.23,"y":-0.56,"z":5.0,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}
The fourth image file to be uploaded.
JSON-encoded metadata for image4.
{"x":10.0,"y":-2.0,"z":0.0,"qx":0.0,"qy":1.0,"qz":0.0,"qw":0.0}
Query successful
Bad request
Unauthorized - Missing or invalid token
Map/MapSet not found (if applicable)
Internal server error
POST /v1/vps/map/multi-image-query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 697
{
"isRightHanded": "true",
"width": "960",
"height": "720",
"px": "478.838623046875",
"py": "365.346618652343",
"fx": "670.4620971679688",
"fy": "670.4620971679688",
"mapId": "",
"mapCode": "",
"mapSetId": "",
"mapSetCode": "",
"image1": "binary",
"image1_data": "{\"x\":-5.1772,\"y\":0.2936,\"z\":-2.6439,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
"image2": "binary",
"image2_data": "{\"x\":-3.12,\"y\":1.01,\"z\":2.56,\"qx\":0.0,\"qy\":0.707,\"qz\":0.0,\"qw\":0.707}",
"image3": "binary",
"image3_data": "{\"x\":1.23,\"y\":-0.56,\"z\":5.0,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
"image4": "binary",
"image4_data": "{\"x\":10.0,\"y\":-2.0,\"z\":0.0,\"qx\":0.0,\"qy\":1.0,\"qz\":0.0,\"qw\":0.0}"
}
{
"success": true,
"location": {
"position": {
"x": -5.1772,
"y": 0.2936,
"z": -2.6439
},
"rotation": {
"qx": -0.0185,
"qy": 0.9949,
"qz": -0.0691,
"qw": 0.0703
}
},
"confidence": 0.89,
"mapId": "66ca3f3b773b18f09e131279"
}
Query a VPS object using an uploaded image and camera parameters. Accepts objectCode to identify the target object, and returns the query result from the external API.
The code of the VPS object
OBJ-001
Camera intrinsic parameter fx (focal length x-axis)
1000.0
Camera intrinsic parameter fy (focal length y-axis)
1000.0
Camera intrinsic parameter px (principal point x-coordinate)
640.0
Camera intrinsic parameter py (principal point y-coordinate)
480.0
Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string ("true" or "false").
true
Possible values: The width (in pixels) of the input image
1280
The height (in pixels) of the input image
720
The image file to query against the object
Query successful
Bad request - Invalid parameters or missing required fields
Unauthorized - Missing or invalid token
Forbidden - Access denied
Object not found
Internal server error
POST /v1/vps/object/query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Content-Type: multipart/form-data
Accept: */*
Content-Length: 153
{
"objectCode": "OBJ-001",
"fx": "1000.0",
"fy": "1000.0",
"px": "640.0",
"py": "480.0",
"isRightHanded": "true",
"width": "1280",
"height": "720",
"queryImage": "binary"
}
{
"success": true,
"result": {
"position": {
"x": 2.1234,
"y": 1.5678,
"z": 0.9876
},
"rotation": {
"qx": 0.0123,
"qy": 0.4567,
"qz": 0.0789,
"qw": 0.8901
},
"confidence": 0.92
},
"message": "Query successful."
}
Generates a temporary, pre-signed URL for downloading a file from S3
Unique identifier for the file
671b454e33d6dc761ca15156/6756c20336a9794c6effce42/Mesh/TexturedMesh.glb
Successfully generated pre-signed URL
Unauthorized - Invalid or expired token
File not found
Server error
GET /v1/file HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
"url": "https://amazonaws.com/671bX-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=%2Faws4_request&X-Amz-Date=20241658753a8c6380ad6d01c217e1ad978d88e2ba6a4&X-Amz-SignedHeaders=host&x-id=GetObject"
}
Get the list of all Mapsets in an account
Retrieves a paginated list of MapSets associated with the authenticated user's account
Number of items to return per page
10
Example: 10
Page number for pagination
1
Example: 1
MapSets retrieved successfully
Bad Request - Invalid parameters
Unauthorized
Internal Server Error - Something went wrong on the server
GET /v1/vps/map-set HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
"data": [
{
"id": "66ca3f3b773b18f09e131280",
"name": "Office Buildings Collection",
"description": "Collection of office building maps",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"status": "active",
"mapCount": 3
}
],
"pagination": {
"totalItems": 12,
"totalPages": 2,
"currentPage": 1,
"itemsPerPage": 10
}
}
Get details of all maps of a specific Mapset using MapSetID
Fetches details of a specific map set using its unique ID.
The unique ID of the map set.
67a5c7fca18f6052c5b21653
Map set details retrieved successfully
Invalid map set ID
Unauthorized - Authorization header missing or invalid
Map set not found
Internal server error
GET /v1/vps/map-set/{mapSetId} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
"mapSet": {
"_id": "67a5c7fca18f6052c5b21653",
"name": "purva test new 141",
"accountId": "67192b1b65071c55d950d11f",
"mapSetCode": "MSET_7J7SUEFVMSV1",
"status": "active",
"messages": [],
"createdAt": "2025-02-07T08:44:44.607Z",
"updatedAt": "2025-02-07T08:44:44.607Z",
"mapSetData": [
{
"_id": "67a5c7fc58eda5c8bfaedc2e",
"createdAt": "2025-02-07T08:44:44.614Z",
"order": 0,
"relativePose": {
"position": {
"x": 0,
"y": 0,
"z": 0
},
"rotation": {
"qx": 0,
"qy": 0,
"qz": 0,
"qw": 1
}
},
"updatedAt": "2025-02-07T08:44:44.614Z",
"map": {
"_id": "67a4a02ba18f6052c5b20833",
"accountId": "67192b1b65071c55d950d11f",
"mapName": "141",
"status": "active",
"storage": 66.59728527069092,
"mapCode": "MAP_XCQWQYKZ26U2",
"createdAt": "2025-02-06T11:42:35.504Z",
"updatedAt": "2025-02-07T08:44:44.620Z",
"mapMesh": {
"rawMesh": {
"type": "glb",
"meshLink": "67192b150d11f/67a4a02b5b20833/Mesh/Mesh.glb"
},
"texturedMesh": {
"type": "glb",
"meshLink": "67192b1b6d11f/67a4a02ba2c5b20833/Mesh/TexturedMesh.glb"
}
},
"thumbnail": "67192b10d11f/67a4a022c833/RGB/Rgb_20250206114139457.jpg",
"coordinates": {
"latitude": 22.89059543609619,
"longitude": 57.63724517822266,
"altitude": 901.3638305664062
}
}
}
]
}
}
Retrieves a paginated list of VPS objects. You can use query parameters to filter or search objects by name, and control pagination settings.
The page number for pagination (starting from 1)
1
Example: 1
Number of records per page (maximum 100)
10
Example: 10
Filter or search text for partial match on object names
Multiset
A paginated list of VPS objects retrieved successfully
Bad request - Invalid query parameters
Unauthorized - Missing or invalid token
Internal server error
GET /v1/vps/object HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer JWT
Accept: */*
{
"data": [
{
"_id": "67a5b08736cb3f76aaf3a416",
"objectName": "Multiset Object 1",
"trackingType": "side",
"source": {
"provider": "web",
"fileType": "glb",
"coordinateSystem": "RHS"
}
},
{
"_id": "67a5b08736cb3f76aaf3a417",
"objectName": "Multiset Object 2",
"trackingType": "top",
"source": {
"provider": "mobile",
"fileType": "obj",
"coordinateSystem": "LHS"
}
}
],
"currentPage": 1,
"totalPages": 5,
"totalCount": 42
}