# Copyright 2016 OpenMarket Ltd # # 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. swagger: '2.0' info: title: "Matrix Client-Server Content Repository API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/media/%CLIENT_MAJOR_VERSION% consumes: - application/json - "*/*" produces: - application/json - "*/*" securityDefinitions: $ref: definitions/security.yaml paths: "/upload": post: summary: Upload some content to the content repository. operationId: uploadContent produces: ["application/json"] security: - accessToken: [] parameters: - in: header name: Content-Type type: string description: The content type of the file being uploaded x-example: "Content-Type: audio/mpeg" - in: query type: string x-example: "War and Peace.pdf" name: filename description: The name of the file being uploaded - in: body name: "" description: The content to be uploaded. required: true schema: type: string example: "" format: byte responses: 200: description: The MXC URI for the uploaded content. schema: type: object required: ["content_uri"] properties: content_uri: type: string description: "The MXC URI to the uploaded content." examples: application/json: { "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" } 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}": get: summary: "Download content from the content repository." operationId: getContent produces: ["*/*"] parameters: - in: path type: string name: serverName x-example: matrix.org required: true description: | The server name from the ``mxc://`` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the ``mxc://`` URI (the path component) responses: 200: description: "The content that was previously uploaded." headers: Content-Type: description: "The content type of the file that was previously uploaded." type: "string" Content-Disposition: description: "The name of the file that was previously uploaded, if set." type: "string" schema: type: file 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media "/download/{serverName}/{mediaId}/{fileName}": get: summary: "Download content from the content repository as a given filename." operationId: getContentOverrideName produces: ["*/*"] parameters: - in: path type: string name: serverName x-example: matrix.org required: true description: | The server name from the ``mxc://`` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the ``mxc://`` URI (the path component) - in: path type: string name: fileName x-example: filename.jpg required: true description: | The filename to give in the Content-Disposition responses: 200: description: "The content that was previously uploaded." headers: Content-Type: description: "The content type of the file that was previously uploaded." type: "string" Content-Disposition: description: "The name of file given in the request" type: "string" schema: type: file 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media "/thumbnail/{serverName}/{mediaId}": get: summary: "Download a thumbnail of the content from the content repository." operationId: getContentThumbnail produces: ["image/jpeg", "image/png"] parameters: - in: path type: string name: serverName required: true x-example: matrix.org description: | The server name from the ``mxc://`` URI (the authoritory component) - in: path type: string name: mediaId x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the ``mxc://`` URI (the path component) - in: query type: integer x-example: 64 name: width description: |- The *desired* width of the thumbnail. The actual thumbnail may not match the size specified. - in: query type: integer x-example: 64 name: height description: |- The *desired* height of the thumbnail. The actual thumbnail may not match the size specified. - in: query type: string enum: ["crop", "scale"] name: method x-example: "scale" description: The desired resizing method. responses: 200: description: "A thumbnail of the requested content." headers: Content-Type: description: "The content type of the thumbnail." type: "string" enum: ["image/jpeg", "image/png"] schema: type: file 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media "/preview_url": get: summary: "Get information about a URL for a client" operationId: getUrlPreview produces: ["application/json"] security: - accessToken: [] parameters: - in: query type: string x-example: "https://matrix.org" name: url description: "The URL to get a preview of" required: true - in: query type: number x-example: 1510610716656 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. 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 are described here. schema: type: object properties: "matrix:image:size": type: number description: |- The byte-size of the image. Omitted if there is no image attached. "og:image": type: string description: |- An MXC URI to the image. Omitted if there is no image. examples: application/json: { "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: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media "/config": get: summary: Get the configuration for the content repository. 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. Clients should handle such situations gracefully. operationId: getConfig produces: ["application/json"] security: - accessToken: [] responses: 200: description: The public content repository configuration for the matrix server. schema: type: object properties: m.upload.size: type: number 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: application/json: { "m.upload.size": 50000000 } 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Media