mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-25 12:34:10 +01:00
C2S: Drop /upload and /create because we aren't replacing them today
This commit is contained in:
Travis Ralston
parent
f10abb3613
commit
c998b8a018
|
|
@ -17,204 +17,6 @@ info:
|
||||||
title: Matrix Client-Server Content Repository API
|
title: Matrix Client-Server Content Repository API
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
paths:
|
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"
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
"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}":
|
"/media/v3/download/{serverName}/{mediaId}":
|
||||||
get:
|
get:
|
||||||
deprecated: true
|
deprecated: true
|
||||||
|
|
@ -589,20 +391,6 @@ components:
|
||||||
accessTokenBearer:
|
accessTokenBearer:
|
||||||
$ref: definitions/security.yaml#/accessTokenBearer
|
$ref: definitions/security.yaml#/accessTokenBearer
|
||||||
parameters:
|
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:
|
serverName:
|
||||||
in: path
|
in: path
|
||||||
name: serverName
|
name: serverName
|
||||||
|
|
@ -664,26 +452,7 @@ components:
|
||||||
schema:
|
schema:
|
||||||
type: boolean
|
type: boolean
|
||||||
default: false
|
default: false
|
||||||
requestBodies:
|
|
||||||
bytes:
|
|
||||||
content:
|
|
||||||
application/octet-stream:
|
|
||||||
example: <bytes>
|
|
||||||
description: The content to be uploaded.
|
|
||||||
required: true
|
|
||||||
responses:
|
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:
|
rateLimited:
|
||||||
description: This request was rate-limited.
|
description: This request was rate-limited.
|
||||||
content:
|
content:
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue