---
title: "Update media metadata"
method: PATCH
path: "/buckets/{slug}/media/{media_id}"
tags: ["Media"]
---

# Update media metadata

`PATCH /buckets/{slug}/media/{media_id}`

Update the folder, alt text, or user metadata on a media item. The underlying file is not replaced: to change the file, upload a new one via `https://workers.cosmicjs.com` and repoint the referencing Metafields.

## Request body

- MediaUpdate — Only the properties sent are changed. The underlying file cannot be replaced through this endpoint.
  - `folder` string
  - `alt_text` string — Images only.
  - `metadata` object
  - `trigger_webhook` boolean

## Response `200`

The updated media item.

- MediaResponse
  - `media` Media, required — An image, file, or document in the Bucket.
    - `id` string
    - `name` string — Unique file name within the Bucket. This is the value you assign to a File or Image Metafield.
    - `original_name` string — The file name as uploaded.
    - `size` union — File size in bytes.
      - integer
      - string
    - `type` string — MIME type.
    - `bucket` string — Bucket id.
    - `folder` string, nullable
    - `alt_text` string, nullable — Images only.
    - `width` integer, nullable — Pixel width. Images only.
    - `height` integer, nullable — Pixel height. Images only.
    - `url` string, uri — CDN URL.
    - `imgix_url` string, uri — imgix URL, which accepts image processing query parameters.
    - `metadata` object, nullable — Arbitrary JSON metadata you attach to the media.
    - `created_at` string, date-time

## Other responses

- `400` — The request was invalid, most often a malformed `query` or a Metafield value that failed validation.
- `401` — The access key is missing or incorrect.
- `402` — The Bucket needs to be upgraded before it can be used again.
- `404` — The addressed resource does not exist in this Bucket. Note that this covers a resource missing from a route that exists; an unrecognized route answers 200 with a `Route not found` body instead, as described in the API description above.
- `429` — Too many requests hit the API too quickly. Back off and retry.
- `500` — Something went wrong on the Cosmic side.

---

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