@ -22,26 +22,13 @@ paths:
summary : Upload some content to the content repository. summary : Upload some content to the content repository.
operationId : uploadContent operationId : uploadContent
security: security:
- accessToken : [ ] - accessTokenQuery : [ ]
- accessTokenBearer : [ ]
parameters: parameters:
- in : header - $ref : '#/components/parameters/contentType'
name : Content-Type - $ref : '#/components/parameters/filename'
description : The content type of the file being uploaded
example : application/pdf
schema:
type : string
- in : query
name : filename
description : The name of the file being uploaded
example : War and Peace.pdf
schema:
type : string
requestBody: requestBody:
content: $ref : '#/components/requestBodies/bytes'
application/octet-stream:
example : <bytes>
description : The content to be uploaded.
required : true
responses: responses:
"200" : "200" :
description : The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for description : The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for
@ -55,7 +42,8 @@ paths:
properties: properties:
content_uri: content_uri:
type : string type : string
format : uri format : mx-mxc-uri
pattern : "^mxc:\\/\\/"
description : The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to description : The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
the uploaded content. the uploaded content.
examples: examples:
@ -80,23 +68,9 @@ paths:
"error": "Cannot upload this content" "error": "Cannot upload this content"
} }
"413" : "413" :
description : The uploaded content is too large for the server. $ref : '#/components/responses/uploadTooLarge'
content:
application/json:
schema:
$ref : definitions/errors/error.yaml
examples:
response:
value : {
"errcode": "M_TOO_LARGE" ,
"error": "Cannot upload files larger than 100mb"
}
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
tags: tags:
- Media - Media
"/media/v3/upload/{serverName}/{mediaId}" : "/media/v3/upload/{serverName}/{mediaId}" :
@ -108,40 +82,16 @@ paths:
operationId : uploadContentToMXC operationId : uploadContentToMXC
x-addedInMatrixVersion : "1.7" x-addedInMatrixVersion : "1.7"
parameters: parameters:
- in : path - $ref : '#/components/parameters/serverName'
name : serverName
required : true
description : | description : |
The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component). The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authority component).
example : matrix.org - $ref : '#/components/parameters/mediaId'
schema:
type : string
- in : path
name : mediaId
required : true
description : | description : |
The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component). The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component).
example : ascERGshawAWawugaAcauga - $ref : '#/components/parameters/contentType'
schema: - $ref : '#/components/parameters/filename'
type : string
- in : header
name : Content-Type
description : The content type of the file being uploaded
example : application/pdf
schema:
type : string
- in : query
name : filename
description : The name of the file being uploaded
example : War and Peace.pdf
schema:
type : string
requestBody: requestBody:
content: $ref : '#/components/requestBodies/bytes'
application/octet-stream:
example : <bytes>
description : The content to be uploaded.
required : true
responses: responses:
"200" : "200" :
description : The upload was successful. description : The upload was successful.
@ -189,23 +139,9 @@ paths:
"error": "Media already uploaded" "error": "Media already uploaded"
} }
"413" : "413" :
description : The uploaded content is too large for the server. $ref : '#/components/responses/uploadTooLarge'
content:
application/json:
schema:
$ref : definitions/errors/error.yaml
examples:
response:
value : {
"errcode": "M_TOO_LARGE" ,
"error": "Cannot upload files larger than 100mb"
}
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
tags: tags:
- Media - Media
/media/v1/create: /media/v1/create:
@ -234,7 +170,8 @@ paths:
operationId : createContent operationId : createContent
x-addedInMatrixVersion : "1.7" x-addedInMatrixVersion : "1.7"
security: security:
- accessToken : [ ] - accessTokenQuery : [ ]
- accessTokenBearer : [ ]
# empty json object # empty json object
responses: responses:
"200" : "200" :
@ -249,7 +186,8 @@ paths:
properties: properties:
content_uri: content_uri:
type : string type : string
format : uri format : mx-mxc-uri
pattern : "^mxc:\\/\\/"
description : |- description : |-
The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at
which the content will be available, once it is uploaded. which the content will be available, once it is uploaded.
@ -274,11 +212,7 @@ paths:
"error": "Cannot upload this content" "error": "Cannot upload this content"
} }
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
tags: tags:
- Media - Media
"/media/v3/download/{serverName}/{mediaId}" : "/media/v3/download/{serverName}/{mediaId}" :
@ -286,68 +220,17 @@ paths:
summary : Download content from the content repository. summary : Download content from the content repository.
operationId : getContent operationId : getContent
parameters: parameters:
- in : path - $ref : '#/components/parameters/serverName'
name : serverName - $ref : '#/components/parameters/mediaId'
required : true - $ref : '#/components/parameters/allow_remote'
description : | - $ref : '#/components/parameters/timeout_ms'
The server name from the `mxc://` URI (the authoritory component) - $ref : '#/components/parameters/allow_redirect'
example : matrix.org
schema:
type : string
- in : path
name : mediaId
required : true
description : |
The media ID from the `mxc://` URI (the path component)
example : ascERGshawAWawugaAcauga
schema:
type : string
- 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
- 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 can and should impose a maximum value for this
parameter. The content repository may also choose to respond before
the timeout.
example : 5000
schema:
type : integer
format : int64
default : 20000
- 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
responses: responses:
"200" : "200" :
description : The content that was previously uploaded. description : The content that was previously uploaded.
headers: headers:
Content-Type: Content-Type:
description : The content type of the file that was previously uploaded. $ref : '#/components/headers/downloadContentType'
schema:
type : string
Content-Disposition: Content-Disposition:
description : The name of the file that was previously uploaded, if set. description : The name of the file that was previously uploaded, if set.
schema: schema:
@ -358,51 +241,15 @@ paths:
# This is a workaround for us not being able to say the response is required. # This is a workaround for us not being able to say the response is required.
description : "**Required.** The bytes for the uploaded file." description : "**Required.** The bytes for the uploaded file."
"307" : "307" :
description : A redirect to the thumbnail of the requested content. $ref : '#/components/responses/downloadRedirect'
headers:
Location:
description : The URL of the thumbnail content.
schema:
type : string
"308" : "308" :
description : A redirect to the thumbnail of the requested content. $ref : '#/components/responses/downloadRedirect'
headers:
Location:
description : The URL of the thumbnail content.
schema:
type : string
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
"502" : "502" :
description : The content is too large for the server to serve. $ref : '#/components/responses/downloadTooLarge'
content:
application/json:
schema:
$ref : definitions/errors/error.yaml
examples:
response:
value : {
"errcode": "M_TOO_LARGE" ,
"error": "Content is too large to serve"
}
"504" : "504" :
description : |- $ref : '#/components/responses/notYetUploaded'
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"
}
tags: tags:
- Media - Media
"/media/v3/download/{serverName}/{mediaId}/{fileName}" : "/media/v3/download/{serverName}/{mediaId}/{fileName}" :
@ -414,22 +261,8 @@ paths:
provided by the caller. provided by the caller.
operationId : getContentOverrideName operationId : getContentOverrideName
parameters: parameters:
- in : path - $ref : '#/components/parameters/serverName'
name : serverName - $ref : '#/components/parameters/mediaId'
required : true
description : |
The server name from the `mxc://` URI (the authoritory component)
example : matrix.org
schema:
type : string
- in : path
name : mediaId
required : true
description : |
The media ID from the `mxc://` URI (the path component)
example : ascERGshawAWawugaAcauga
schema:
type : string
- in : path - in : path
name : fileName name : fileName
required : true required : true
@ -437,52 +270,15 @@ paths:
example : filename.jpg example : filename.jpg
schema: schema:
type : string type : string
- in : query - $ref : '#/components/parameters/allow_remote'
name : allow_remote - $ref : '#/components/parameters/timeout_ms'
required : false - $ref : '#/components/parameters/allow_redirect'
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
- 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 can and should impose a maximum value for this
parameter. The content repository may also choose to respond before
the timeout.
example : 5000
schema:
type : integer
format : int64
default : 20000
- 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
responses: responses:
"200" : "200" :
description : The content that was previously uploaded. description : The content that was previously uploaded.
headers: headers:
Content-Type: Content-Type:
description : The content type of the file that was previously uploaded. $ref : '#/components/headers/downloadContentType'
schema:
type : string
Content-Disposition: Content-Disposition:
description : |- description : |-
The `fileName` requested or the name of the file that was previously The `fileName` requested or the name of the file that was previously
@ -495,51 +291,15 @@ paths:
# This is a workaround for us not being able to say the response is required. # This is a workaround for us not being able to say the response is required.
description : "**Required.** The bytes for the uploaded file." description : "**Required.** The bytes for the uploaded file."
"307" : "307" :
description : A redirect to the thumbnail of the requested content. $ref : '#/components/responses/downloadRedirect'
headers:
Location:
description : The URL of the thumbnail content.
schema:
type : string
"308" : "308" :
description : A redirect to the thumbnail of the requested content. $ref : '#/components/responses/downloadRedirect'
headers:
Location:
description : The URL of the thumbnail content.
schema:
type : string
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
"502" : "502" :
description : The content is too large for the server to serve. $ref : '#/components/responses/downloadTooLarge'
content:
application/json:
schema:
$ref : definitions/errors/error.yaml
examples:
response:
value : {
"errcode": "M_TOO_LARGE" ,
"error": "Content is too large to serve"
}
"504" : "504" :
description : |- $ref : '#/components/responses/notYetUploaded'
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"
}
tags: tags:
- Media - Media
"/media/v3/thumbnail/{serverName}/{mediaId}" : "/media/v3/thumbnail/{serverName}/{mediaId}" :
@ -550,22 +310,8 @@ paths:
See the [Thumbnails](/client-server-api/#thumbnails) section for more information. See the [Thumbnails](/client-server-api/#thumbnails) section for more information.
operationId : getContentThumbnail operationId : getContentThumbnail
parameters: parameters:
- in : path - $ref : '#/components/parameters/serverName'
name : serverName - $ref : '#/components/parameters/mediaId'
required : true
description : |
The server name from the `mxc://` URI (the authoritory component)
example : example.org
schema:
type : string
- in : path
name : mediaId
required : true
description : |
The media ID from the `mxc://` URI (the path component)
example : ascERGshawAWawugaAcauga
schema:
type : string
- in : query - in : query
name : width name : width
required : true required : true
@ -595,44 +341,31 @@ paths:
enum: enum:
- crop - crop
- scale - scale
- $ref : '#/components/parameters/allow_remote'
- $ref : '#/components/parameters/timeout_ms'
- $ref : '#/components/parameters/allow_redirect'
- in : query - in : query
name : allow_remote name : animated
required : false x-addedInMatrixVersion : "1.11"
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
- 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 can and should impose a maximum value for this
parameter. The content repository may also choose to respond before
the timeout.
example : 5000
schema:
type : integer
format : int64
default : 20000
- in : query
name : allow_redirect
x-addedInMatrixVersion : "1.7"
required : false required : false
description : | description : |
Indicates to the server that it may return a 307 or 308 redirect response that points Indicates preference for an animated thumbnail from the server, if possible. Animated
at the relevant media content. When not explicitly set to true the server must return thumbnails typically use the content types `image/gif`, `image/png` (with APNG format),
the media content itself. `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 example : false
schema: schema:
type : boolean type : boolean
default : false
responses: responses:
"200" : "200" :
description : A thumbnail of the requested content. description : A thumbnail of the requested content.
@ -644,6 +377,9 @@ paths:
enum: enum:
- image/jpeg - image/jpeg
- image/png - image/png
- image/apng
- image/gif
- image/webp
content: content:
image/jpeg: image/jpeg:
schema: schema:
@ -651,21 +387,27 @@ paths:
description : "**Required.** The bytes for the thumbnail." description : "**Required.** The bytes for the thumbnail."
image/png: image/png:
schema: schema:
description : "**Required.** The bytes for the thumbnail." x-changedInMatrixVersion:
"307" : "1.11": The PNG may be of the APNG variety if animation is supported and requested.
description : A redirect to the thumbnail of the requested content. description : |
headers: **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated
Location: format if `animated=true`.
description : The URL of the thumbnail content. image/apng:
schema: schema:
type : string x-addedInMatrixVersion : "1.11"
"308" : description : "**Required.** The bytes for the *animated* thumbnail."
description : A redirect to the thumbnail of the requested content. image/gif:
headers:
Location:
description : The URL of the thumbnail content.
schema: schema:
type : string 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" : "400" :
description : |- description : |-
The request does not make sense to the server, or the server cannot thumbnail The request does not make sense to the server, or the server cannot thumbnail
@ -694,11 +436,7 @@ paths:
"error": "Content is too large to thumbnail" "error": "Content is too large to thumbnail"
} }
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
"502" : "502" :
description : The remote content is too large for the server to thumbnail. description : The remote content is too large for the server to thumbnail.
content: content:
@ -712,19 +450,7 @@ paths:
"error": "Content is too large to thumbnail" "error": "Content is too large to thumbnail"
} }
"504" : "504" :
description : |- $ref : '#/components/responses/notYetUploaded'
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"
}
tags: tags:
- Media - Media
/media/v3/preview_url: /media/v3/preview_url:
@ -741,7 +467,8 @@ paths:
being shared should also not be shared with the homeserver. being shared should also not be shared with the homeserver.
operationId : getUrlPreview operationId : getUrlPreview
security: security:
- accessToken : [ ] - accessTokenQuery : [ ]
- accessTokenBearer : [ ]
parameters: parameters:
- in : query - in : query
name : url name : url
@ -793,11 +520,7 @@ paths:
"matrix:image:size": 102400 "matrix:image:size": 102400
} }
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/rate_limited.yaml
tags: tags:
- Media - Media
/media/v3/config: /media/v3/config:
@ -816,7 +539,8 @@ paths:
than is advertised by the server on this endpoint. than is advertised by the server on this endpoint.
operationId : getConfig operationId : getConfig
security: security:
- accessToken : [ ] - accessTokenQuery : [ ]
- accessTokenBearer : [ ]
responses: responses:
"200" : "200" :
description : The public content repository configuration for the matrix server. description : The public content repository configuration for the matrix server.
@ -838,11 +562,7 @@ paths:
"m.upload.size": 50000000 "m.upload.size": 50000000
} }
"429" : "429" :
description : This request was rate-limited. $ref : '#/components/responses/rateLimited'
content:
application/json:
schema:
$ref : definitions/errors/error.yaml
tags: tags:
- Media - Media
servers: servers:
@ -859,4 +579,157 @@ servers:
default : /_matrix default : /_matrix
components: components:
securitySchemes: securitySchemes:
$ref : definitions/security.yaml accessTokenQuery:
$ref : definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref : definitions/security.yaml#/accessTokenBearer
parameters:
contentType:
in : header
name : Content-Type
description : The content type of the file being uploaded
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 can and should impose a maximum value for this parameter. The
content repository may also choose to 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:
example : <bytes>
description : The content to be uploaded.
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.
schema:
type : string
Johannes Marbach