---
title: "Upload content to an `mxc://` URI that was created earlier."
method: PUT
path: "/_matrix/media/v3/upload/{serverName}/{mediaId}"
tags: ["Media"]
---

# Upload content to an \`mxc://\` URI that was created earlier.

`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/media/v3/upload/{serverName}/{mediaId}`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/media/v3/upload/:serverName/:mediaId/put.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint permits uploading content to an `mxc://` URI that was created
earlier via [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create).

## Path parameters

- `serverName` string, mx-server-name, required
- `mediaId` string, required

## Query parameters

- `filename` string

## Headers

- `Content-Type` string

## Request body `application/octet-stream`

- string: The content to be uploaded.

## Response `200`

The upload was successful.

- object

## Other responses

- `403`: The user does not have permission to upload the content. Some reasons for this error include: - The server does not permit the file type. - The user has reached a quota for uploaded content. - The request comes from a different user than the one that called [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create). A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response) will be returned with the `errcode` `M_FORBIDDEN`.
- `404`: The user has provided an invalid MXC ID. Some reasons for this error include: - The MXC ID was not created with [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create). - The MXC ID has expired. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_FOUND`.
- `409`: The endpoint was called with a media ID that already has content. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response) will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`.
- `413`: The uploaded content is too large for the server.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)