async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/content-repo.yaml

@@ -0,0 +1,887 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Content Repository API
+  version: 1.0.0
+paths:
+  /media/v3/upload:
+    post:
+      summary: Upload some content to the content repository.
+      operationId: uploadContent
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/contentType'
+        - $ref: '#/components/parameters/filename'
+      requestBody:
+        $ref: '#/components/requestBodies/bytes'
+      responses:
+        "200":
+          description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
+            the uploaded content.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - content_uri
+                properties:
+                  content_uri:
+                    type: string
+                    format: mx-mxc-uri
+                    pattern: "^mxc:\\/\\/"
+                    description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
+                      the uploaded content.
+              examples:
+                response:
+                  value: {
+                    "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
+                  }
+        "403":
+          description: |-
+            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.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot upload this content"
+                  }
+        "413":
+          $ref: '#/components/responses/uploadTooLarge'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+  "/media/v3/upload/{serverName}/{mediaId}":
+    put:
+      summary: Upload content to an `mxc://` URI that was created earlier.
+      description: |-
+        This endpoint permits uploading content to an `mxc://` URI that was created
+        earlier via [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create).
+      operationId: uploadContentToMXC
+      x-addedInMatrixVersion: "1.7"
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+          description: |
+            The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authority component).
+        - $ref: '#/components/parameters/mediaId'
+          description: |
+            The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component).
+        - $ref: '#/components/parameters/contentType'
+        - $ref: '#/components/parameters/filename'
+      requestBody:
+        $ref: '#/components/requestBodies/bytes'
+      responses:
+        "200":
+          description: The upload was successful.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
+          description: |-
+            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](/client-server-api/#post_matrixmediav1create).
+
+            A [standard error response](/client-server-api/#standard-error-response)
+            will be returned with the `errcode` `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot upload this content"
+                  }
+        "404":
+          description: |-
+            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](/client-server-api/#post_matrixmediav1create).
+            - The MXC ID has expired.
+
+            A [standard error response](/client-server-api/#standard-error-response)
+            will be returned with the `errcode` `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown media ID"
+                  }
+        "409":
+          description: |-
+            The endpoint was called with a media ID that already has content. A
+            [standard error response](/client-server-api/#standard-error-response)
+            will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_CANNOT_OVERWRITE_MEDIA",
+                    "error": "Media already uploaded"
+                  }
+        "413":
+          $ref: '#/components/responses/uploadTooLarge'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+  /media/v1/create:
+    post:
+      summary: Create a new `mxc://` URI without uploading the content.
+      description: |-
+        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}`](/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`.
+      operationId: createContent
+      x-addedInMatrixVersion: "1.7"
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      # empty json object
+      responses:
+        "200":
+          description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
+            the uploaded content.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - content_uri
+                properties:
+                  content_uri:
+                    type: string
+                    format: mx-mxc-uri
+                    pattern: "^mxc:\\/\\/"
+                    description: |-
+                      The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at
+                      which the content will be available, once it is uploaded.
+                    example: mxc://example.com/AQwafuaFswefuhsfAFAgsw
+                  unused_expires_at:
+                    type: integer
+                    format: int64
+                    description: |-
+                      The timestamp (in milliseconds since the unix epoch) when the
+                      generated media id will expire, if media is not uploaded.
+                    example: 1647257217083
+        "403":
+          description: The user does not have permission to upload the content.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Cannot upload this content"
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+  "/media/v3/download/{serverName}/{mediaId}":
+    get:
+      deprecated: true
+      summary: Download content from the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{% changed-in v="1.11" %}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
+      operationId: getContent
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
+      responses:
+        "200":
+          description: The content that was previously uploaded.
+          headers:
+            Content-Type:
+              $ref: '#/components/headers/downloadContentType'
+            Content-Disposition:
+              x-changedInMatrixVersion:
+                "1.12": This header became required.
+              description: |
+                The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
+                of the returned content. MUST be one of `inline` or `attachment`,
+                and SHOULD contain a file name.
+
+                If the `Content-Type` is allowed in the [restrictions for serving
+                inline content](/client-server-api/#serving-inline-content),
+                servers SHOULD use `inline`, otherwise they SHOULD use
+                `attachment`.
+
+                If the upload was made with a `filename`, this header MUST
+                contain the same `filename`. Otherwise, `filename` is excluded
+                from the header. If the media being downloaded is remote, the
+                remote server's `filename` in the `Content-Disposition` header
+                is used as the `filename` instead. When the header is not
+                supplied, or does not supply a `filename`, the local download
+                response does not include a `filename`.
+              required: true
+              schema:
+                type: string
+                example: "inline; filename=\"filename.jpg\""
+          content:
+            application/octet-stream:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the uploaded file."
+        "307":
+          $ref: '#/components/responses/downloadRedirect'
+        "308":
+          $ref: '#/components/responses/downloadRedirect'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          $ref: '#/components/responses/downloadTooLarge'
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  "/media/v3/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      deprecated: true
+      summary: Download content from the content repository overriding the file name
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename)
+        (requires authentication).
+        {{% /boxes/note %}}
+
+        This will download content from the content repository (same as
+        the previous endpoint) but replace the target file name with the one
+        provided by the caller.
+
+        {{% boxes/warning %}}
+        {{% changed-in v="1.11" %}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
+      operationId: getContentOverrideName
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - in: path
+          name: fileName
+          required: true
+          description: A filename to give in the `Content-Disposition` header.
+          example: filename.jpg
+          schema:
+            type: string
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
+      responses:
+        "200":
+          description: The content that was previously uploaded.
+          headers:
+            Content-Type:
+              $ref: '#/components/headers/downloadContentType'
+            Content-Disposition:
+              x-changedInMatrixVersion:
+                "1.12": This header became required.
+              description: |
+                The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
+                of the returned content. MUST be one of `inline` or `attachment`,
+                and MUST contain the file name requested in the path.
+
+                If the `Content-Type` is allowed in the [restrictions for serving
+                inline content](/client-server-api/#serving-inline-content),
+                servers SHOULD use `inline`, otherwise they SHOULD use
+                `attachment`.
+              required: true
+              schema:
+                type: string
+                example: "inline; filename=\"filename.jpg\""
+          content:
+            application/octet-stream:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the uploaded file."
+        "307":
+          $ref: '#/components/responses/downloadRedirect'
+        "308":
+          $ref: '#/components/responses/downloadRedirect'
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          $ref: '#/components/responses/downloadTooLarge'
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  "/media/v3/thumbnail/{serverName}/{mediaId}":
+    get:
+      deprecated: true
+      summary: Download a thumbnail of content from the content repository
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid)
+        (requires authentication).
+        {{% /boxes/note %}}
+
+        Download a thumbnail of content from the content repository.
+        See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
+
+        {{% boxes/warning %}}
+        {{% changed-in v="1.11" %}} This endpoint MAY return `404 M_NOT_FOUND`
+        for media which exists, but is after the server froze unauthenticated
+        media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more
+        information.
+        {{% /boxes/warning %}}
+      operationId: getContentThumbnail
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - in: query
+          name: width
+          required: true
+          description: |-
+            The *desired* width of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: height
+          required: true
+          description: |-
+            The *desired* height of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+          example: 64
+          schema:
+            type: integer
+        - in: query
+          name: method
+          description: |-
+            The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails)
+            section for more information.
+          example: scale
+          schema:
+            type: string
+            enum:
+              - crop
+              - scale
+        - $ref: '#/components/parameters/allow_remote'
+        - $ref: '#/components/parameters/timeout_ms'
+        - $ref: '#/components/parameters/allow_redirect'
+        - in: query
+          name: animated
+          x-addedInMatrixVersion: "1.11"
+          required: false
+          description: |
+            Indicates preference for an animated thumbnail from the server, if possible. Animated
+            thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
+            `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`
+            content types.
+
+            When `true`, the server SHOULD return an animated thumbnail if possible and supported.
+            When `false`, the server MUST NOT return an animated thumbnail. For example, returning a
+            static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT
+            return an animated thumbnail.
+
+            Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation.
+
+            When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the
+            server SHOULD behave as though `animated` is `false`.
+          example: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: A thumbnail of the requested content.
+          headers:
+            Content-Disposition:
+              x-addedInMatrixVersion: "1.12"
+              description: |
+                The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
+                of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`).
+
+                Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content),
+                as these limitations imply which formats should be used for thumbnail generation.
+              required: true
+              schema:
+                type: string
+                example: "inline; filename=\"thumbnail.png\""
+            Content-Type:
+              x-changedInMatrixVersion:
+                "1.12": |
+                  This header became required in order to support `Content-Disposition`.
+              description: The content type of the thumbnail.
+              required: true
+              schema:
+                type: string
+                enum:
+                  - image/jpeg
+                  - image/png
+                  - image/apng
+                  - image/gif
+                  - image/webp
+          content:
+            image/jpeg:
+              schema:
+                # This is a workaround for us not being able to say the response is required.
+                description: "**Required.** The bytes for the thumbnail."
+            image/png:
+              schema:
+                x-changedInMatrixVersion:
+                  "1.11": The PNG may be of the APNG variety if animation is supported and requested.
+                description: |
+                  **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
+                  format if `animated=true`.
+            image/apng:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/gif:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+            image/webp:
+              schema:
+                x-addedInMatrixVersion: "1.11"
+                description: "**Required.** The bytes for the *animated* thumbnail."
+        "307":
+          $ref: '#/components/responses/thumbnailRedirect'
+        "308":
+          $ref: '#/components/responses/thumbnailRedirect'
+        "400":
+          description: |-
+            The request does not make sense to the server, or the server cannot thumbnail
+            the content. For example, the client requested non-integer dimensions or asked
+            for negatively-sized images.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "Cannot generate thumbnails for the requested content"
+                  }
+        "413":
+          description: The local content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+        "502":
+          description: The remote content is too large for the server to thumbnail.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_TOO_LARGE",
+                    "error": "Content is too large to thumbnail"
+                  }
+        "504":
+          $ref: '#/components/responses/notYetUploaded'
+      tags:
+        - Media
+  /media/v3/preview_url:
+    get:
+      deprecated: true
+      summary: Get information about a URL for a client
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url).
+        {{% /boxes/note %}}
+
+        Get information about a URL for the client. Typically this is called when a
+        client sees a URL in a message and wants to render a preview for the user.
+
+        **Note:**
+        Clients should consider avoiding this endpoint for URLs posted in encrypted
+        rooms. Encrypted rooms often contain more sensitive information the users
+        do not want to share with the homeserver, and this can mean that the URLs
+        being shared should also not be shared with the homeserver.
+      operationId: getUrlPreview
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: url
+          description: The URL to get a preview of.
+          required: true
+          example: https://matrix.org
+          schema:
+            type: string
+            format: uri
+        - in: query
+          name: ts
+          description: |-
+            The preferred point in time to return a preview for. The server may
+            return a newer version if it does not have the requested version
+            available.
+          example: 1510610716656
+          schema:
+            type: integer
+            format: int64
+      responses:
+        "200":
+          description: |-
+            The OpenGraph data for the URL, which may be empty. Some values are
+            replaced with matrix equivalents if they are provided in the response.
+            The differences from the [OpenGraph](https://ogp.me/) protocol are
+            described here.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  matrix:image:size:
+                    type: integer
+                    format: int64
+                    description: The byte-size of the image. Omitted if there is no image attached.
+                  og:image:
+                    type: string
+                    format: uri
+                    description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
+                      the image. Omitted if there is no image.
+                additionalProperties:
+                    description: |-
+                      Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
+              examples:
+                response:
+                  value: {
+                    "og:title": "Matrix Blog Post",
+                    "og:description": "This is a really cool blog post from matrix.org",
+                    "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
+                    "og:image:type": "image/png",
+                    "og:image:height": 48,
+                    "og:image:width": 48,
+                    "matrix:image:size": 102400
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+  /media/v3/config:
+    get:
+      deprecated: true
+      summary: Get the configuration for the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig).
+        {{% /boxes/note %}}
+
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        **NOTE:** Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+      operationId: getConfig
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The public content repository configuration for the matrix server.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  m.upload.size:
+                    type: integer
+                    format: int64
+                    description: |-
+                      The maximum size an upload can be in bytes.
+                      Clients SHOULD use this as a guide when uploading content.
+                      If not listed or null, the size limit should be treated as unknown.
+              examples:
+                response:
+                  value: {
+                    "m.upload.size": 50000000
+                  }
+        "429":
+          $ref: '#/components/responses/rateLimited'
+      tags:
+        - Media
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
+  parameters:
+    contentType:
+      in: header
+      name: Content-Type
+      description: |
+        **Optional.** The content type of the file being uploaded.
+
+        Clients SHOULD always supply this header.
+
+        Defaults to `application/octet-stream` if it is not set.
+      x-changedInMatrixVersion:
+        "1.12": |
+          This header became explicitly optional with a default value.
+      example: application/pdf
+      schema:
+        type: string
+    filename:
+      in: query
+      name: filename
+      description: The name of the file being uploaded
+      example: War and Peace.pdf
+      schema:
+        type: string
+    serverName:
+      in: path
+      name: serverName
+      required: true
+      description: |
+        The server name from the `mxc://` URI (the authority component).
+      example: matrix.org
+      schema:
+        type: string
+        format: mx-server-name
+    mediaId:
+      in: path
+      name: mediaId
+      required: true
+      description: |
+        The media ID from the `mxc://` URI (the path component).
+      example: ascERGshawAWawugaAcauga
+      schema:
+        type: string
+    allow_remote:
+      in: query
+      name: allow_remote
+      required: false
+      description: |-
+        Indicates to the server that it should not attempt to fetch the media if
+        it is deemed remote. This is to prevent routing loops where the server
+        contacts itself.
+
+        Defaults to `true` if not provided.
+      example: false
+      schema:
+        type: boolean
+        default: true
+    timeout_ms:
+      in: query
+      name: timeout_ms
+      x-addedInMatrixVersion: "1.7"
+      description: |
+        The maximum number of milliseconds that the client is willing to wait to
+        start receiving data, in the case that the content has not yet been
+        uploaded. The default value is 20000 (20 seconds). The content
+        repository SHOULD impose a maximum value for this parameter. The
+        content repository MAY respond before the timeout.
+      example: 5000
+      schema:
+        type: integer
+        format: int64
+        default: 20000
+    allow_redirect:
+      in: query
+      name: allow_redirect
+      x-addedInMatrixVersion: "1.7"
+      required: false
+      description: |
+        Indicates to the server that it may return a 307 or 308 redirect
+        response that points at the relevant media content. When not explicitly
+        set to `true` the server must return the media content itself.
+      example: false
+      schema:
+        type: boolean
+        default: false
+  requestBodies:
+    bytes:
+      content:
+        application/octet-stream:
+          schema:
+            description: The content to be uploaded.
+            example: <bytes>
+      required: true
+  responses:
+    uploadTooLarge:
+      description: The uploaded content is too large for the server.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_TOO_LARGE",
+                "error": "Cannot upload files larger than 100mb"
+              }
+    rateLimited:
+      description: This request was rate-limited.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/rate_limited.yaml
+    notYetUploaded:
+      description: |-
+        The content is not yet available. A [standard error response](/client-server-api/#standard-error-response)
+        will be returned with the `errcode` `M_NOT_YET_UPLOADED`.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_NOT_YET_UPLOADED",
+                "error": "Content has not yet been uploaded"
+              }
+    downloadRedirect:
+      description: A redirect to the requested content.
+      headers:
+        Location:
+          description: The URL of the content.
+          schema:
+            type: string
+            format: uri
+    downloadTooLarge:
+      description: The content is too large for the server to serve.
+      content:
+        application/json:
+          schema:
+            $ref: definitions/errors/error.yaml
+          examples:
+            response:
+              value: {
+                "errcode": "M_TOO_LARGE",
+                "error": "Content is too large to serve"
+              }
+    thumbnailRedirect:
+      description: A redirect to the thumbnail of the requested content.
+      headers:
+        Location:
+          description: The URL of the thumbnail content.
+          schema:
+            type: string
+            format: uri
+  headers:
+    downloadContentType:
+      description: |
+        The content type of the file that was previously uploaded.
+
+        The server MUST return a `Content-Type` which is either exactly the same
+        as the original upload, or reasonably close. The bounds of "reasonable"
+        are:
+
+        * Adding a charset to `text/*` content types.
+        * Detecting HTML and using `text/html` instead of `text/plain`.
+        * Using `application/octet-stream` when the server determines the
+          content type is obviously wrong. For example, an encrypted file being
+          claimed as `image/png`.
+        * Returning `application/octet-stream` when the media has an
+          unknown/unprovided `Content-Type`. For example, being uploaded before
+          the server tracked content types or when the remote server is
+          non-compliantly omitting the header entirely.
+        
+        Actions not in the spirit of the above are not considered "reasonable".
+      x-changedInMatrixVersion:
+        "1.12": |
+          This header became required in order to support `Content-Disposition`,
+          and the behaviour to compute its value was clarified.
+      required: true
+      schema:
+        type: string
+