# Files

File upload and download operations

## GET /download

> Generate signed download URL for a file

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/download":{"get":{"summary":"Generate signed download URL for a file","tags":["Files"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"The file URL to generate download link for"}],"responses":{"200":{"description":"Download URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"downloadUrl":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}}
```

## Upload files

> Upload files including images, videos, AR World files, and other content types. MVP: Public access, no authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/upload":{"post":{"summary":"Upload files","description":"Upload files including images, videos, AR World files, and other content types. MVP: Public access, no authentication required.","tags":["Files"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Single file upload"},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Multiple file uploads"}}}}}},"responses":{"200":{"description":"Upload successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/FileUploadResult"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"FileUploadResult":{"type":"object","description":"Result of a successful file upload","properties":{"status":{"type":"string","enum":["success"],"description":"Upload status"},"message":{"type":"string","description":"Success message"},"url":{"type":"string","format":"uri","description":"S3 URL of the uploaded file"},"fileId":{"type":"integer","description":"Database ID of the uploaded file record"},"fileName":{"type":"string","description":"Original filename"},"fileSize":{"type":"integer","nullable":true,"description":"File size in bytes"},"mimeType":{"type":"string","nullable":true,"description":"MIME type of the file"},"arWorldUrl":{"type":"string","format":"uri","nullable":true,"description":"S3 URL for AR World files (.bin), null for other file types"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Upload relocalization reference photo

> Uploads an image to be used as a relocalization reference photo for AR experiences. Only image files are accepted.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"},{"name":"Upload","description":"File upload operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Pass the session token obtained from /auth/sync."}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}},"paths":{"/upload/relocalization":{"post":{"summary":"Upload relocalization reference photo","description":"Uploads an image to be used as a relocalization reference photo for AR experiences. Only image files are accepted.","tags":["Files","Upload"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image file (jpg, jpeg, png, webp, heic, heif)"}}}}}},"responses":{"200":{"description":"Photo uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Full URL to the uploaded image"},"key":{"type":"string","description":"S3 file key (e.g., reloc/uuid-filename.jpg)"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Retrieve or trigger GLB to USDZ conversion

> Retrieves the conversion result for a file, or triggers a new GLB to USDZ conversion if not already converted.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"},{"name":"Upload","description":"File upload operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/upload/{fileId}/converted_file":{"post":{"summary":"Retrieve or trigger GLB to USDZ conversion","description":"Retrieves the conversion result for a file, or triggers a new GLB to USDZ conversion if not already converted.","tags":["Files","Upload"],"parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"integer"},"description":"File ID"}],"responses":{"200":{"description":"Conversion result","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"originalFile":{"type":"object","properties":{"id":{"type":"integer"},"fileName":{"type":"string"},"fileType":{"type":"string","enum":["GLB"]},"fileUrl":{"type":"string","format":"uri"}}},"convertedFile":{"type":"object","properties":{"id":{"type":"integer"},"fileName":{"type":"string"},"fileType":{"type":"string","enum":["USDZ"]},"fileUrl":{"type":"string","format":"uri"},"fileSize":{"type":"integer"}}},"conversionTime":{"type":"string","description":"Time taken for conversion (e.g., '2.34s')"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"408":{"description":"Conversion timeout"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}}
```

## Generate presigned upload URL

> MVP: Public access, no authentication required.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/upload/presigned":{"post":{"summary":"Generate presigned upload URL","description":"MVP: Public access, no authentication required.","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileName","contentType"],"properties":{"fileName":{"type":"string"},"contentType":{"type":"string"}}}}}},"responses":{"200":{"description":"Presigned URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"uploadUrl":{"type":"string"},"key":{"type":"string"},"url":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object"}}}}}}
```

## Retrieve file information including converted USDZ if available

> Retrieves file metadata by fileId. If the file has been converted to USDZ, returns both original and converted file information. Useful for visualizing already processed files without re-uploading.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"},{"name":"Upload","description":"File upload operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/upload/convert":{"get":{"summary":"Retrieve file information including converted USDZ if available","description":"Retrieves file metadata by fileId. If the file has been converted to USDZ, returns both original and converted file information. Useful for visualizing already processed files without re-uploading.","tags":["Files","Upload"],"parameters":[{"name":"fileId","in":"query","required":true,"schema":{"type":"integer"},"description":"ID of the file to retrieve"}],"responses":{"200":{"description":"File information retrieved successfully","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"File with Conversion","properties":{"message":{"type":"string"},"originalFile":{"type":"object","properties":{"id":{"type":"integer","description":"File ID"},"fileName":{"type":"string","description":"Original file name"},"fileType":{"type":"string","enum":["GLB","USDZ"],"description":"Original file type"},"fileUrl":{"type":"string","format":"uri","description":"URL of the original file"}}},"convertedFile":{"type":"object","properties":{"id":{"type":"integer","description":"File ID (same as original)"},"fileName":{"type":"string","description":"Converted USDZ file name"},"fileType":{"type":"string","enum":["USDZ"]},"fileUrl":{"type":"string","format":"uri","description":"URL of the converted USDZ file"},"fileSize":{"type":"integer","description":"Size of the converted file in bytes"}}}}},{"type":"object","title":"File without Conversion","properties":{"message":{"type":"string"},"file":{"type":"object","properties":{"id":{"type":"integer","description":"File ID"},"fileName":{"type":"string","description":"File name"},"fileUrl":{"type":"string","format":"uri","description":"URL of the file"},"fileSize":{"type":"integer","description":"File size in bytes"},"mimeType":{"type":"string","description":"MIME type of the file"},"fileType":{"type":"string","enum":["GLB","USDZ"],"description":"File type"},"conversionStatus":{"type":"string","enum":["NOT_CONVERTED","CONVERTING","CONVERTED","FAILED"],"description":"Current conversion status"}}}}}]}}}},"400":{"description":"fileId is required and must be a number","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Failed to retrieve file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"string","description":"Error details"}}}}}}}}}}}
```

## Upload file with automatic GLB to USDZ conversion

> Uploads a file via multipart/form-data, creates a database record, and automatically converts GLB files to USDZ format. Returns file information including converted USDZ URL if conversion was performed.

```json
{"openapi":"3.0.0","info":{"title":"Zones API","version":"1.0.0"},"tags":[{"name":"Files","description":"File upload and download operations"},{"name":"Upload","description":"File upload operations"}],"servers":[{"url":"/api","description":"API base path"}],"paths":{"/upload/convert":{"post":{"summary":"Upload file with automatic GLB to USDZ conversion","description":"Uploads a file via multipart/form-data, creates a database record, and automatically converts GLB files to USDZ format. Returns file information including converted USDZ URL if conversion was performed.","tags":["Files","Upload"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"File to upload. GLB files will be automatically converted to USDZ."}}}}}},"responses":{"200":{"description":"File uploaded successfully. If GLB file, conversion completed.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"GLB Conversion Response","properties":{"message":{"type":"string"},"originalFile":{"type":"object","properties":{"id":{"type":"integer","description":"File ID"},"fileName":{"type":"string","description":"Original GLB file name"},"fileType":{"type":"string","enum":["GLB"]},"fileUrl":{"type":"string","format":"uri","description":"URL of the original GLB file"}}},"convertedFile":{"type":"object","properties":{"id":{"type":"integer","description":"File ID (same as original)"},"fileName":{"type":"string","description":"Converted USDZ file name"},"fileType":{"type":"string","enum":["USDZ"]},"fileUrl":{"type":"string","format":"uri","description":"URL of the converted USDZ file"},"fileSize":{"type":"integer","description":"Size of the converted file in bytes"}}},"conversionTime":{"type":"string","description":"Time taken for conversion"}}},{"type":"object","title":"Non-GLB Upload Response","properties":{"message":{"type":"string"},"file":{"type":"object","properties":{"id":{"type":"integer","description":"File ID"},"fileName":{"type":"string","description":"File name"},"fileUrl":{"type":"string","format":"uri","description":"URL of the uploaded file"},"fileSize":{"type":"integer","description":"File size in bytes"},"mimeType":{"type":"string","description":"MIME type of the file"},"fileType":{"type":"string","enum":["GLB","USDZ"],"description":"Detected file type"}}}}}]}}}},"400":{"description":"File is required or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"500":{"description":"Upload or conversion failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"string","description":"Error details"}}}}}}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.meshmap.com/api/zones/files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.