Files

File upload and download operations

Generate signed download URL for a file

get

Query parameters

urlstringRequired

The file URL to generate download link for

Responses

200

Download URL generated

application/json

downloadUrlstringOptional

400

Bad request

application/json

500

Internal server error

application/json

get

/download

HTTPcURLJavaScriptPython

GET /api/download?url=text HTTP/1.1
Accept: */*

{
  "downloadUrl": "text"
}

Upload files

post

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

Body

multipart/form-data

filestring · binaryOptional

Single file upload

filesstring · binary[]Optional

Multiple file uploads

Responses

200

Upload successful

application/json

statusstring · enumOptionalPossible values:

400

Bad request

application/json

500

Internal server error

application/json

post

/upload

HTTPcURLJavaScriptPython

POST /api/upload HTTP/1.1
Content-Type: multipart/form-data
Accept: */*
Content-Length: 36

{
  "file": "binary",
  "files": [
    "binary"
  ]
}

{
  "status": "success",
  "results": [
    {
      "status": "success",
      "message": "text",
      "url": "https://example.com",
      "fileId": 1,
      "fileName": "text",
      "fileSize": 1,
      "mimeType": "text",
      "arWorldUrl": "https://example.com"
    }
  ]
}

Upload relocalization reference photo

post

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

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer token authentication. Pass the session token obtained from /auth/sync.

Body

multipart/form-data

filestring · binaryRequired

Image file (jpg, jpeg, png, webp, heic, heif)

Responses

200

Photo uploaded successfully

application/json

urlstring · uriOptional

Full URL to the uploaded image

keystringOptional

S3 file key (e.g., reloc/uuid-filename.jpg)

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/upload/relocalization

HTTPcURLJavaScriptPython

POST /api/upload/relocalization HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

{
  "url": "https://example.com",
  "key": "text"
}

Retrieve or trigger GLB to USDZ conversion

post

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

Path parameters

fileIdintegerRequired

File ID

Responses

200

Conversion result

application/json

messagestringOptional

conversionTimestringOptional

Time taken for conversion (e.g., '2.34s')

400

Bad request

application/json

404

Resource not found

application/json

408

Conversion timeout

500

Internal server error

application/json

post

/upload/{fileId}/converted_file

HTTPcURLJavaScriptPython

POST /api/upload/{fileId}/converted_file HTTP/1.1
Accept: */*

{
  "message": "text",
  "originalFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "GLB",
    "fileUrl": "https://example.com"
  },
  "convertedFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "USDZ",
    "fileUrl": "https://example.com",
    "fileSize": 1
  },
  "conversionTime": "text"
}

Generate presigned upload URL

post

MVP: Public access, no authentication required.

Body

application/json

fileNamestringRequired

contentTypestringRequired

Responses

200

Presigned URL generated

application/json

uploadUrlstringOptional

keystringOptional

urlstringOptional

400

Bad request

application/json

500

Internal server error

application/json

post

/upload/presigned

HTTPcURLJavaScriptPython

POST /api/upload/presigned HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "fileName": "text",
  "contentType": "text"
}

{
  "uploadUrl": "text",
  "key": "text",
  "url": "text"
}

Retrieve file information including converted USDZ if available

get

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.

Query parameters

fileIdintegerRequired

ID of the file to retrieve

Responses

200

File information retrieved successfully

application/json

or

400

fileId is required and must be a number

application/json

404

File not found

application/json

500

Failed to retrieve file

application/json

get

/upload/convert

HTTPcURLJavaScriptPython

GET /api/upload/convert?fileId=1 HTTP/1.1
Accept: */*

{
  "message": "File found with conversion",
  "originalFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "GLB",
    "fileUrl": "https://example.com"
  },
  "convertedFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "USDZ",
    "fileUrl": "https://example.com",
    "fileSize": 1
  }
}

Upload file with automatic GLB to USDZ conversion

post

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.

Body

multipart/form-data

filestring · binaryRequired

File to upload. GLB files will be automatically converted to USDZ.

Responses

200

File uploaded successfully. If GLB file, conversion completed.

application/json

or

400

File is required or invalid

application/json

500

Upload or conversion failed

application/json

post

/upload/convert

HTTPcURLJavaScriptPython

POST /api/upload/convert HTTP/1.1
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

{
  "message": "File uploaded and converted successfully",
  "originalFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "GLB",
    "fileUrl": "https://example.com"
  },
  "convertedFile": {
    "id": 1,
    "fileName": "text",
    "fileType": "USDZ",
    "fileUrl": "https://example.com",
    "fileSize": 1
  },
  "conversionTime": "5.23s"
}