mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-24 03:54: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
|
||||
version: 1.0.0
|
||||
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}":
|
||||
get:
|
||||
deprecated: true
|
||||
|
|
@ -589,20 +391,6 @@ components:
|
|||
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
|
||||
|
|
@ -664,26 +452,7 @@ components:
|
|||
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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue