---
title: "Create a new `mxc://` URI without uploading the content."
method: POST
path: "/_matrix/media/v1/create"
tags: ["Media"]
---

# Create a new \`mxc://\` URI without uploading the content.

`POST /_matrix/media/v1/create`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/media/v1/create`
- 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/v1/create/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later
via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](https://spec.matrix.org/v1.19/client-server-api/#put_matrixmediav3uploadservernamemediaid).

The server may optionally enforce a maximum age for unused IDs,
and delete media IDs when the client doesn't start the upload in time,
or when the upload was interrupted and not resumed in time. The server
should include the maximum POSIX millisecond timestamp to complete the
upload in the `unused_expires_at` field in the response JSON. The
recommended default expiration is 24 hours which should be enough time
to accommodate users on poor connection who find a better connection to
complete the upload.

As well as limiting the rate of requests to create `mxc://` URIs, the server
should limit the number of concurrent *pending media uploads* a given
user can have. A pending media upload is a created `mxc://` URI where (a)
the media has not yet been uploaded, and (b) has not yet expired (the
`unused_expires_at` timestamp has not yet passed). In both cases, the
server should respond with an HTTP 429 error with an errcode of
`M_LIMIT_EXCEEDED`.

## Response `200`

The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) for the uploaded content.

- object
  - `content_uri` string, mx-mxc-uri, required: The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) at which the content will be available, once it is uploaded.
  - `unused_expires_at` integer: The timestamp (in milliseconds since the unix epoch) when the generated media id will expire, if media is not uploaded.

## Other responses

- `403`: The user does not have permission to upload the content.
- `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)