> 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/map-upload/matterpak-upload.md).
# MatterPak Upload
The VPS Map Creation API accepts a POST request to /v1/vps/map with a JSON payload containing map metadata and Matterport authentication.
## Create a VPS Map using MatterPak
> Creates a new VPS map from a Matterport space using MatterPak.\
> \
> \*\*Authentication Options:\*\*\
> You can authenticate with Matterport using one of two methods:\
> 1\. \*\*OAuth Token\*\*: Use \`oauthToken\` in the metadata\
> 2\. \*\*Client Credentials\*\*: Use both \`clientId\` and \`clientSecret\` in the metadata\
> \
> \*\*Process Flow:\*\*\
> 1\. Submit map creation request with Matterport space ID and credentials\
> 2\. System fetches the MatterPak from Matterport using provided credentials\
> 3\. Map is processed in the cloud (no file upload required)\
> 4\. Map becomes available for VPS queries when processing completes\
> \
> \*\*Note:\*\* The map name will be automatically truncated to 30 characters if longer.
```json
{"openapi":"3.0.0","info":{"title":"VPS Map Creation API - MatterPak","version":"1.0.0"},"servers":[{"url":"https://api.multiset.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Standard Authorization header using the Bearer scheme.\n\nYou can obtain a bearer token by:\n1. Authenticating through /v1/auth/login endpoint\n2. Using M2M (Machine-to-Machine) credentials via /v1/m2m/token endpoint\n\nExample: \"Authorization: Bearer {your-jwt-token}\"\n"}},"schemas":{"CreateMatterPakMapRequest":{"type":"object","required":["mapName","coordinates","source"],"properties":{"mapName":{"type":"string","description":"Name of the VPS map (will be truncated to 30 characters if longer).\nShould be descriptive and unique to help identify the map.\n","minLength":3,"maxLength":255},"coordinates":{"type":"object","description":"Geographic coordinates where the map is located","required":["latitude","longitude","altitude"],"properties":{"latitude":{"type":"number","format":"double","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees"},"longitude":{"type":"number","format":"double","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees"},"altitude":{"type":"number","format":"double","description":"Altitude in meters above sea level"}}},"heading":{"type":"number","format":"double","minimum":0,"maximum":360,"description":"Optional heading/orientation in degrees (0-360)"},"source":{"type":"object","description":"Source configuration for the MatterPak map","required":["provider","fileType","coordinateSystem","processType","metadata"],"properties":{"provider":{"type":"string","enum":["matterport"],"description":"Must be \"matterport\" for MatterPak maps"},"fileType":{"type":"string","enum":["matterpak"],"description":"Must be \"matterpak\" for MatterPak maps"},"coordinateSystem":{"type":"string","enum":["RHS","LHS"],"description":"Coordinate system used by the map:\n- RHS: Right-Hand Coordinate System\n- LHS: Left-Hand Coordinate System\n"},"processType":{"type":"string","enum":["cloud"],"description":"Must be \"cloud\" for MatterPak maps (processed server-side)"},"metadata":{"type":"object","description":"Matterport authentication and space information.\nYou must provide either:\n1. spaceId + oauthToken, OR\n2. spaceId + clientId + clientSecret\n","required":["spaceId"],"properties":{"spaceId":{"type":"string","description":"Matterport space ID (model ID) to create the VPS map from.\nYou can get this from the Matterport API or dashboard.\n"},"oauthToken":{"type":"string","description":"Matterport OAuth token for authentication.\nUse this OR clientId/clientSecret (not both).\n"},"clientId":{"type":"string","description":"Matterport Client ID for authentication.\nMust be used together with clientSecret.\n"},"clientSecret":{"type":"string","description":"Matterport Client Secret for authentication.\nMust be used together with clientId.\n"}},"oneOf":[{"required":["spaceId","oauthToken"]},{"required":["spaceId","clientId","clientSecret"]}]}}}}},"CreateMapResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"mapId":{"type":"string","description":"Unique identifier for the created map"},"status":{"type":"string","enum":["processing","active","failed"],"description":"Current processing status of the map"},"mapName":{"type":"string","description":"Name of the created map"},"estimatedProcessingTime":{"type":"string","description":"Estimated time for map processing to complete"}},"required":["message","mapId","status","mapName"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A message detailing the error"},"code":{"type":"integer","description":"Error code (optional)"}},"required":["error"]}}},"paths":{"/v1/vps/map":{"post":{"summary":"Create a VPS Map using MatterPak","description":"Creates a new VPS map from a Matterport space using MatterPak.\n\n**Authentication Options:**\nYou can authenticate with Matterport using one of two methods:\n1. **OAuth Token**: Use `oauthToken` in the metadata\n2. **Client Credentials**: Use both `clientId` and `clientSecret` in the metadata\n\n**Process Flow:**\n1. Submit map creation request with Matterport space ID and credentials\n2. System fetches the MatterPak from Matterport using provided credentials\n3. Map is processed in the cloud (no file upload required)\n4. Map becomes available for VPS queries when processing completes\n\n**Note:** The map name will be automatically truncated to 30 characters if longer.\n","tags":["VPS Maps"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMatterPakMapRequest"}}}},"responses":{"201":{"description":"Map creation request submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMapResponse"}}}},"400":{"description":"Bad request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Matterport authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# 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/map-upload/matterpak-upload.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.