---
title: "Upload a file into the vault"
method: POST
path: "/api/files/upload"
tags: ["files"]
---

# Upload a file into the vault

`POST /api/files/upload`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/files/upload`
- Auth: HTTP bearer

Clerk session or agt_ token with `files:write` (live tier re-checked). The agent path sends `application/json` with the bytes base64-encoded in `content_base64`; the browser panel sends `multipart/form-data` with a `file` part (that variant is not described by this schema). Naming a `folder_id` requires the caller to manage that folder. The response carries the new id, never a blob URL.

## Request body

- FileUploadRequest: The JSON (agent) upload variant. The browser panel posts the same fields as multipart/form-data with a `file` part instead of `content_base64`.
  - `filename` string, required
  - `content_base64` string, required: The file bytes, base64-encoded.
  - `content_type` string: MIME type; guessed from the filename when omitted.
  - `folder_id` string: Target folder. Must exist AND be one the caller manages; omit for the vault root.
  - `visibility` 'private' | 'ic-members' | 'grantees'
  - `grantees` string[]: Clerk user ids to admit (with visibility: grantees).
  - `label` string
  - `description` string
  - `tags` string[]

## Response `200`

File stored.

- FileUploadResponse
  - `ok` boolean, required
  - `id` string, required: Use this with /api/files/{id} and the download route.
  - `filename` string, required
  - `size` integer, required
  - `visibility` string, required
  - `via` 'clerk' | 'agent'

## Other responses

- `400`: Unreadable upload, missing content_base64, empty file, invalid folder_id, or a rejected filename/visibility.
- `401`: No auth.
- `403`: Scope/tier not authorized, or not allowed to add files to that folder.
- `404`: folder_id names no folder.
- `413`: Body exceeds the upload ceiling for this transport.
- `429`: Per-member file-count quota reached — delete some first.
- `500`: Blob or KV write 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)