async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,590 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2019-2024 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 (Authenticated) Content Repository API
+  version: 1.0.0
+paths:
+  "/media/download/{serverName}/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download content from the content repository.
+      description: |-
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - $ref: '#/components/parameters/serverName'
+        - $ref: '#/components/parameters/mediaId'
+        - $ref: '#/components/parameters/timeout_ms'
+      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/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download content from the content repository overriding the file name.
+      description: |-
+        This will download content from the content repository (same as
+        the previous endpoint) but replaces the target file name with the one
+        provided by the caller.
+
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentOverrideNameAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      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/timeout_ms'
+      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/thumbnail/{serverName}/{mediaId}":
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Download a thumbnail of content from the content repository
+      description: |-
+        Download a thumbnail of content from the content repository.
+        See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
+
+        {{% boxes/note %}}
+        Clients SHOULD NOT generate or use URLs which supply the access token in
+        the query string. These URLs may be copied by users verbatim and provided
+        in a chat message to another user, disclosing the sender's access token.
+        {{% /boxes/note %}}
+
+        Clients MAY be redirected using the 307/308 responses below to download
+        the request object. This is typical when the homeserver uses a Content
+        Delivery Network (CDN).
+      operationId: getContentThumbnailAuthed
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      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/timeout_ms'
+        - 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/preview_url:
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Get information about a URL for a client
+      description: |-
+        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.
+
+        {{% boxes/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.
+        {{% /boxes/note %}}
+      operationId: getUrlPreviewAuthed
+      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 protocol](https://ogp.me/) 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/config:
+    get:
+      x-addedInMatrixVersion: "1.11"
+      summary: Get the configuration for the content repository.
+      description: |-
+        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.
+
+        {{% boxes/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.
+        {{% /boxes/note %}}
+      operationId: getConfigAuthed
+      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/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer
+  parameters:
+    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
+    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
+  responses:
+    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
+