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

# 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: "<content>"
          description: The content to be uploaded.
          required: true
          schema:
            type: string
            example: "<bytes>"
            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. Ommitted 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