Map Upload

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 // xgrid // faro
    "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

bearerAuth

AuthorizationstringRequired

Standard Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Body

application/json

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

messagestringRequired

Success message

Example: Map created successfully

mapCodestringRequired

Unique code for the created VPS map

Example: MAP-ABC123

mapIdstringRequired

Unique identifier for the created VPS map

Example: 67a5b08736cb3f76aaf3a416

keystringRequired

S3 key path for the uploaded file

Example: accountId/mapId/mapId.zip

400

Bad request - Invalid input data, plan limits exceeded, or plan expired

application/json

401

Unauthorized - Missing or invalid token

application/json

500

Internal server error

application/json

post

/vps/map

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Standard Authorization header using the Bearer scheme. Example: "Authorization: Bearer {token}"

Path parameters

idstringRequired

Unique identifier of the VPS map (MongoDB ObjectId)

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

Body

application/json

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

400

Bad request - Invalid upload data or missing required fields

application/json

401

Unauthorized - Missing or invalid token

application/json

404

Not found - VPS map not found

application/json

500

Internal server error during upload completion

application/json

post

/vps/map/complete-upload/{id}

HTTPcURLJavaScriptPython

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"
}