Developer PortalContact UsTutorials

Map Upload API

The VPS mapping APIs work together in a two-step process to upload large map files efficiently using S3 multipart upload. Here's how to use them:

Step 1: Create Map - Call POST /v2/vps/map with your map metadata (name, coordinates, file size, etc.). This API validates your account limits, creates a map entry in the database, and returns multiple presigned S3 URLs for uploading file chunks. You'll receive a mapId, uploadId, and an array of signedUrls for parallel uploads.

Choose source object based on scan type

  "source": {
    "provider": "unity", // matterport // leica // navvis
    "fileType": "zip", // e57
    "coordinateSystem": "RHS" // LHS
  }

For example, the source object for Matterport e57 and Navvis will be

    "provider": "matterport"
    "fileType": "e57"
    "coordinateSystem": "RHS"
  }
    "provider": "navvis"
    "fileType": "e57"
    "coordinateSystem": "RHS"
  }

For example, the source object for Matterport e57 will be

Step 2: Upload File Parts - Split your map file into chunks and upload each chunk to the corresponding presigned URL using standard HTTP PUT requests. Each successful upload returns an ETag, which you must capture and store.

Step 3: Complete Upload - Call POST /v2/vps/map/complete-upload/{mapId} with the uploadId, S3 key, and an array of all the ETags and PartNumbers from step 2. This finalizes the S3 multipart upload, combines all chunks into a single file, and marks your map as ready for processing.

The entire process supports large files up to 25GB, provides progress tracking during uploads, allows for retry logic on failed parts, and includes comprehensive error handling for account limits,authentication, and upload failures. Once completed successfully, your map will enter the processing queue and be available for VPS queries within your application.

Create a new VPS map

post

Creates a new VPS map entry and initiates the S3 multipart upload process. This endpoint validates the map data, checks account limits, and returns S3 upload URLs for file upload.

Authorizations
Body
mapNamestringRequired

Human-readable name for the VPS map

Example: Office Floor 1 Map
fileSizenumber · min: 1Required

Size of the file to be uploaded in bytes

Example: 52428800
headingnumber · max: 360Optional

Optional heading direction in degrees

Example: 45
Responses
201

VPS map created successfully with upload URLs

application/json
post
POST /v2/vps/map HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "mapName": "Office Floor 1 Map",
  "fileSize": 52428800,
  "coordinates": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 50
  },
  "heading": 45,
  "source": {
    "provider": "unity",
    "fileType": "zip",
    "coordinateSystem": "RHS"
  }
}
{
  "message": "Map created successfully",
  "mapCode": "MAP-ABC123",
  "mapId": "67a5b08736cb3f76aaf3a416",
  "uploadUrls": {
    "uploadId": "upload-id-123",
    "signedUrls": [
      {
        "partNumber": 1,
        "signedUrl": "https://s3.amazonaws.com/bucket/path?uploadId=123&partNumber=1"
      },
      {
        "partNumber": 2,
        "signedUrl": "https://s3.amazonaws.com/bucket/path?uploadId=123&partNumber=2"
      }
    ]
  },
  "key": "accountId/mapId/mapId.zip"
}

Complete VPS map multipart upload

post

Completes the S3 multipart upload process for a VPS map. This endpoint should be called after all file parts have been uploaded to S3 using the provided upload URLs.

Authorizations
Path parameters
idstringRequired

Unique identifier of the VPS map (MongoDB ObjectId)

Example: 67a5b08736cb3f76aaf3a416Pattern: ^[a-fA-F0-9]{24}$
Body
uploadIdstringRequired

The upload ID returned from the map creation endpoint

Example: upload-id-123
keystringRequired

The S3 key for the uploaded file

Example: accountId/mapId/mapId.zip
Responses
200

VPS map multipart upload completed successfully

application/json
post
POST /v2/vps/map/complete-upload/{id} HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 206

{
  "uploadId": "upload-id-123",
  "key": "accountId/mapId/mapId.zip",
  "parts": [
    {
      "ETag": "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"",
      "PartNumber": 1
    },
    {
      "ETag": "\"70ee1738b6b21e2c8a43f3a5ab0eee71\"",
      "PartNumber": 2
    }
  ]
}
{
  "message": "Map uploaded successfully"
}
PreviousREST API DocsNextMatterPak Upload API

Last updated

Was this helpful?