---
title: "Create a staged media upload intent"
method: POST
path: "/media/upload-intents"
tags: ["Media"]
---

# Create a staged media upload intent

`POST /media/upload-intents`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/media/upload-intents`
- Auth: HTTP bearer

Creates a short-lived direct-upload intent for media bytes that cannot travel through a JSON or code argument. POST the original file bytes to the returned uploadUrl, then complete the intent with the returned storageId.

## Request body

- MediaUploadIntentCreate
  - `filename` string, required
  - `mimeType` string, required
  - `sizeBytes` integer, required
  - `purpose` 'board_logo' | 'board_hero' | 'account_avatar' | 'company_logo' | 'blog_image', required
  - `resourceType` string
  - `resourceId` string

## Response `201`

Upload intent created.

- MediaUploadIntent
  - `id` string, required: Opaque staged media upload intent identifier.
  - `object` 'media_upload_intent', required
  - `uploadUrl` string, uri, required: Short-lived URL that accepts the original raw file bytes.
  - `expiresAt` string, date-time, required

## Other responses

- `400`: The upload metadata is invalid.
- `403`: The caller lacks permission for this purpose.
- `413`: The declared file size exceeds the purpose limit.
- `415`: The declared MIME type is unsupported.
- `429`: Too many uploads.

## Changes

- **2026-10-19** `c34152c38176`: 5 info
  - added the optional property `error/upgrade` to the response with the `400` status
  - added the optional property `error/upgrade` to the response with the `403` status
  - added the optional property `error/upgrade` to the response with the `413` status
  - added the optional property `error/upgrade` to the response with the `415` status
  - …1 more

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/media/upload-intents/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)