---
title: "Rename or move a file, set its alt text, title or tags, or restore it"
method: PATCH
path: "/media/{id}"
tags: ["Media"]
---

# Rename or move a file, set its alt text, title or tags, or restore it

`PATCH /media/{id}`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/media/{id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `sites:write`)

name and folder change the path in the library (the extension stays); the 640 version moves with it. A site keeps the file under the path it has until you deploy again. alt sets the alt text; null removes it. title, description and tags (replacing the old ones) are yours to fill. restore: true puts a file from the trash back on its old path (or next to it when that is taken now); a file in the trash cannot change otherwise (409). 409 conflict when another file already has the new path.

## Path parameters

- `id` string, uuid, required

## Request body

- MediaUpdate: Rename or move a file in the library, set its alt text, title, description or tags, or restore it from the trash. Sites keep the file under the path they have until you deploy again.
  - `name` string: A new file name. The extension always stays that of the file.
  - `folder` string, nullable: Move the file to this folder under /media/; null or an empty string for /media/ itself.
  - `alt` string, nullable: The alt text for the image; null removes it.
  - `title` string, nullable: A display name; null removes it.
  - `description` string, nullable: A free description; null removes it.
  - `tags` string[]: The tags of the file, replacing the old ones; [] removes them. At most 20.
  - `restore` true: Put a file from the trash back where it was (or next to it, when that name is taken now).

## Response `200`

The file after the change.

- MediaFile: A file in the project's media library (Files).
  - `id` string, uuid, required: The id of the file in the library.
  - `path` string, required: Where the file goes on a site when you add it with deploy_site media, like /media/portfolio/project-12/03.webp.
  - `folder` string, required: The folder under /media/, empty for /media/ itself.
  - `name` string, required: The file name in the library.
  - `original_name` string, nullable, required: The name on the user's computer, when it differs.
  - `content_type` string, required
  - `bytes` integer, required
  - `width` integer, nullable, required
  - `height` integer, nullable, required
  - `alt` string, nullable, required: The alt text, set with update_media.
  - `url` string, nullable, required: Where the file is served, on the first site that has it at this path. null: it is on no site yet; it is private until you add it with deploy_site media.
  - `variants` object, required: For photos: 640, the small version for srcset and thumbnails.
  - `srcset` string, nullable, required: A ready srcset for an img tag once the file is on a site: small webp versions at 160, 320, 640 and 1280 wide (from /_hypamoon/img on that site) plus the file itself. Always add sizes with the width it is shown at, like sizes="52px" for a thumbnail.
  - `thumbnail_url` string, nullable, required: A small webp, 160 wide, for thumbnails up to about 80 px (search suggestions, lists, a cart). null while the file is on no site, or for a file that is not a photo.
  - `original_kept` boolean, required: The full-size original is kept privately. It never goes on a site; the user downloads it in the portal.
  - `sites` object[], required: The sites that use this file right now, with the path and url there.
    - `site_id` string, uuid, required
    - `name` string, required
    - `path` string, required
    - `url` string, required
  - `source` 'upload' | 'portaal' | 'site' | 'import', required: upload: an upload link; portaal: the portal; site: it was already on a site; import: an import.
  - `access` 'team' | 'public' | 'paid', required: Who can open the file. team: only the project's members and this chat (the default for every file).
  - `title` string, nullable, required: A display name, set with update_media.
  - `description` string, nullable, required: A free description, set with update_media.
  - `tags` string[], required: Tags to filter on, set with update_media.
  - `kind` 'image' | 'video' | 'audio' | 'pdf' | 'font' | 'archive' | 'document' | 'data' | 'other', required: image, video, audio, pdf, font, archive, document, data or other, from the file type.
  - `deleted_at` string, nullable, required: When it went to the trash; null when it is not in the trash. A file stays in the trash for 30 days.
  - `purge_at` string, nullable, required: When the trash deletes it for good. Restore it before then with update_media restore: true.
  - `deleted_from` string, nullable, required: The path it had before it went to the trash; restore puts it back there.
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `404`: Not Found: not_found.
- `409`: Conflict: conflict.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)