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