---
title: "Upload a media file to the site blob store"
method: POST
path: "/api/upload-media"
tags: ["media", "browser-session"]
---

# Upload a media file to the site blob store

`POST /api/upload-media`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/upload-media`
- Auth: API key in cookie `__session`

Clerk ADMIN session only (NOT reachable with an agt_ bearer). Takes the bytes base64-encoded in a JSON body rather than multipart, preserving the wire format the existing site clients already send. `mediaType` is derived server-side from the content type plus the filename extension and echoed back so a caller can drop the result into the right block field. Script-capable types (SVG/XML/HTML) are refused outright with a 415 — an uploaded SVG is a stored-XSS vector against the very operator session that uploaded it.

## Request body

- MediaUploadRequest
  - `data` string, required: The file bytes, base64-encoded. 10MB decoded ceiling.
  - `filename` string: Used for the 3D-format extension hints and for the stored path; non-alphanumerics are replaced with underscores.
  - `contentType` string, required: image/*, video/*, model/*, or a .glb/.gltf/.splat/.ply filename. SVG/XML/HTML are refused.

## Response `200`

The hosted file.

- MediaUploadResponse
  - `url` string, required: Public blob URL of the stored file.
  - `contentType` string, required: Echoed back unchanged.
  - `mediaType` 'image' | 'video' | 'model3d' | 'gaussianSplat', required: Derived server-side from the content type + extension, so the caller does not have to classify it.

## Other responses

- `400`: Invalid JSON, missing data/contentType, undecodable base64, or an unsupported file type.
- `401`: Not signed in as an admin.
- `413`: File exceeds the 10MB ceiling.
- `415`: Script-capable content type (SVG/XML/HTML).
- `500`: Blob upload failed.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)