---
title: "Rename or move a media file"
method: PATCH
path: "/media/{id}"
tags: ["Media"]
---

# Rename or move a media file

`PATCH /media/{id}`

Update the human-readable name and/or move a media file into a folder. Lets you label assets so they can be found later by name instead of re-uploading. Only the fields you send are changed.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string — Human-readable label (e.g. "pp-play5get50"). Send an empty string to clear it.
  - `folder_id` string, nullable — Move the file into this folder. Send null to move it to the root ("All media").

## Response `200`

Media updated

- object
  - `data` Media
    - `id` string — Media ID (use this in post creation)
    - `url` string — Permanent CDN URL for the media
    - `thumbnail_url` string, nullable — CDN URL of the generated preview thumbnail (videos only; null for images, which use `url` directly)
    - `type` 'image' | 'video'
    - `name` string, nullable — Human-readable label set on upload or via PATCH (e.g. "pp-play5get50"). Falls back to the storage filename when unset. Search this with the `search` query param.
    - `folder_id` string, nullable — Id of the folder this file lives in, or null for the root ("All media")
    - `filename` string — Generated storage filename (stable, used internally)
    - `size` string — Human-formatted file size (e.g. "2.50 MB")
    - `status` 'ready' | 'processing' | 'failed' — Processing state. 'ready' for normal uploads (usable immediately). Large videos uploaded via URL ingestion (over 100 MB) start as 'processing' — poll get media / list media until 'ready' before using them in a post. 'failed' means the source couldn't be fetched or validated.
    - `created_at` string, date-time

## Other responses

- `400` — No updatable fields provided, or folder not found
- `404` — Media not found

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) · [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnisocials/omnisocials-api/revisions/e53b89af0b98/schema)