mirror of
https://github.com/hanzoai/team.git
synced 2026-09-30 01:57:35 +00:00
zeekayandHanzo Dev
404de134f3
The OpenAPI document keys every operation by its full path, so the spec described endpoints that no longer exist the moment the server moved. The openApiSync analyzer cross-checks each registered subrouter against that document and reconstructs the prefix from a literal of its own, so spec and analyzer have to move together or every route reports as missing. Its special case for the v5 root goes away with the root itself. The api/v4 directory keeps its name: it is where the spec sources live, not a URL anyone requests. Co-authored-by: Hanzo Dev <[email protected]>
589 lines
19 KiB
YAML
589 lines
19 KiB
YAML
/v1/team/files:
|
|
post:
|
|
tags:
|
|
- files
|
|
summary: Upload a file
|
|
description: >
|
|
Uploads a file that can later be attached to a post.
|
|
|
|
|
|
This request can either be a multipart/form-data request with a channel_id, files and optional
|
|
|
|
client_ids defined in the FormData, or it can be a request with the channel_id and filename
|
|
|
|
defined as query parameters with the contents of a single file in the body of the request.
|
|
|
|
|
|
Only multipart/form-data requests are supported by server versions up to and including 4.7.
|
|
|
|
Server versions 4.8 and higher support both types of requests.
|
|
|
|
|
|
__Minimum server version__: 9.4
|
|
|
|
Starting with server version 9.4 when uploading a file for a channel bookmark, the bookmark=true query
|
|
parameter should be included in the query string
|
|
|
|
|
|
##### Permissions
|
|
|
|
Must have `upload_file` permission.
|
|
operationId: UploadFile
|
|
parameters:
|
|
- name: channel_id
|
|
in: query
|
|
description: The ID of the channel that this file will be uploaded to
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: filename
|
|
in: query
|
|
description: The name of the file to be uploaded
|
|
required: false
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
files:
|
|
description: A file to be uploaded
|
|
type: string
|
|
format: binary
|
|
channel_id:
|
|
description: The ID of the channel that this file will be uploaded to
|
|
type: string
|
|
client_ids:
|
|
description: A unique identifier for the file that will be returned in
|
|
the response
|
|
type: string
|
|
responses:
|
|
"201":
|
|
description: Corresponding lists of the provided client_ids and the metadata that
|
|
has been stored in the database for each one
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
file_infos:
|
|
description: A list of file metadata that has been stored in the
|
|
database
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/FileInfo"
|
|
client_ids:
|
|
description: A list of the client_ids that were provided in the request
|
|
type: array
|
|
items:
|
|
type: string
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"413":
|
|
$ref: "#/components/responses/TooLarge"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/files/{file_id}":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get a file
|
|
description: |
|
|
Gets a file that has been uploaded previously.
|
|
##### Permissions
|
|
Must have `read_channel` permission or be uploader of the file.
|
|
operationId: GetFile
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
head:
|
|
tags:
|
|
- files
|
|
summary: Get file metadata headers
|
|
description: |
|
|
Performs the same permission and existence checks as getting a file, but returns headers only.
|
|
operationId: HeadFile
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/files/{file_id}/thumbnail":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get a file's thumbnail
|
|
description: |
|
|
Gets a file's thumbnail.
|
|
##### Permissions
|
|
Must have `read_channel` permission or be uploader of the file.
|
|
operationId: GetFileThumbnail
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
head:
|
|
tags:
|
|
- files
|
|
summary: Get thumbnail metadata headers
|
|
description: |
|
|
Performs the same permission and existence checks as getting a thumbnail, but returns headers only.
|
|
operationId: HeadFileThumbnail
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/files/{file_id}/preview":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get a file's preview
|
|
description: |
|
|
Gets a file's preview.
|
|
##### Permissions
|
|
Must have `read_channel` permission or be uploader of the file.
|
|
operationId: GetFilePreview
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
head:
|
|
tags:
|
|
- files
|
|
summary: Get preview metadata headers
|
|
description: |
|
|
Performs the same permission and existence checks as getting a preview, but returns headers only.
|
|
operationId: HeadFilePreview
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/files/{file_id}/link":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get a public file link
|
|
description: >
|
|
Gets a public link for a file that can be accessed without logging into
|
|
Mattermost.
|
|
|
|
##### Permissions
|
|
|
|
Must have `read_channel` permission or be uploader of the file.
|
|
operationId: GetFileLink
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get a link for
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: A publicly accessible link to the given file
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
link:
|
|
type: string
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/v1/team/files/{file_id}/info":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get metadata for a file
|
|
description: |
|
|
Gets a file's info.
|
|
##### Permissions
|
|
Must have `read_channel` permission or be uploader of the file.
|
|
operationId: GetFileInfo
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file info to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: The stored metadata for the given file
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FileInfo"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
"/files/{file_id}/public":
|
|
get:
|
|
tags:
|
|
- files
|
|
summary: Get a public file
|
|
description: |
|
|
##### Permissions
|
|
No permissions required.
|
|
operationId: GetFilePublic
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: h
|
|
in: query
|
|
description: File hash
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
description: Do not have appropriate permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AppError"
|
|
headers:
|
|
First-Inaccessible-File-Time:
|
|
schema:
|
|
type: integer
|
|
description: This header is included with the value "1" if the file is past the cloud's plan limit.
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
head:
|
|
tags:
|
|
- files
|
|
summary: Get public file metadata headers
|
|
description: |
|
|
Performs the same validation checks as getting a public file, but returns headers only.
|
|
operationId: HeadFilePublic
|
|
parameters:
|
|
- name: file_id
|
|
in: path
|
|
description: The ID of the file to get
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: h
|
|
in: query
|
|
description: File hash
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
"501":
|
|
$ref: "#/components/responses/NotImplemented"
|
|
|
|
"/v1/team/teams/{team_id}/files/search":
|
|
post:
|
|
tags:
|
|
- teams
|
|
- files
|
|
- search
|
|
summary: Search files in a team
|
|
description: >
|
|
Search for files in a team based on file name, extention and file
|
|
content (if file content extraction is enabled and supported for the
|
|
files).
|
|
|
|
__Minimum server version__: 5.34
|
|
|
|
##### Permissions
|
|
|
|
Must be authenticated and have the `view_team` permission.
|
|
operationId: SearchFiles
|
|
parameters:
|
|
- name: team_id
|
|
in: path
|
|
description: Team GUID
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- terms
|
|
- is_or_search
|
|
properties:
|
|
terms:
|
|
type: string
|
|
description: The search terms as inputed by the user. To search for files
|
|
from a user include `from:someusername`, using a user's
|
|
username. To search in a specific channel include
|
|
`in:somechannel`, using the channel name (not the display
|
|
name). To search for specific extensions include `ext:extension`.
|
|
is_or_search:
|
|
type: boolean
|
|
description: Set to true if an Or search should be performed vs an And
|
|
search.
|
|
time_zone_offset:
|
|
type: integer
|
|
default: 0
|
|
description: Offset from UTC of user timezone for date searches.
|
|
include_deleted_channels:
|
|
type: boolean
|
|
description: Set to true if deleted channels should be included in the
|
|
search. (archived channels)
|
|
page:
|
|
type: integer
|
|
default: 0
|
|
description: The page to select. (Only works with Elasticsearch)
|
|
per_page:
|
|
type: integer
|
|
default: 60
|
|
description: The number of posts per page. (Only works with Elasticsearch)
|
|
description: The search terms and logic to use in the search.
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Files list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FileInfoList"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
"/v1/team/files/search":
|
|
post:
|
|
tags:
|
|
- files
|
|
- search
|
|
summary: Search files across the teams of the current user
|
|
description: >
|
|
Search for files in the teams of the current user based on file name,
|
|
extention and file content (if file content extraction is enabled and
|
|
supported for the files).
|
|
|
|
__Minimum server version__: 10.2
|
|
|
|
##### Permissions
|
|
|
|
Must be authenticated and have the `view_team` permission.
|
|
operationId: SearchFiles
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- terms
|
|
- is_or_search
|
|
properties:
|
|
terms:
|
|
type: string
|
|
description: The search terms as entered by the user. To search for files
|
|
from a user include `from:someusername`, using a user's
|
|
username. To search in a specific channel include
|
|
`in:somechannel`, using the channel name (not the display
|
|
name). To search for specific extensions include `ext:extension`.
|
|
is_or_search:
|
|
type: boolean
|
|
description: Set to true if an Or search should be performed vs an And
|
|
search.
|
|
time_zone_offset:
|
|
type: integer
|
|
default: 0
|
|
description: Offset from UTC of user timezone for date searches.
|
|
include_deleted_channels:
|
|
type: boolean
|
|
description: Set to true if deleted channels should be included in the
|
|
search. (archived channels)
|
|
page:
|
|
type: integer
|
|
default: 0
|
|
description: The page to select. (Only works with Elasticsearch)
|
|
per_page:
|
|
type: integer
|
|
default: 60
|
|
description: The number of posts per page. (Only works with Elasticsearch)
|
|
description: The search terms and logic to use in the search.
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Files list retrieval successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/FileInfoList"
|
|
"400":
|
|
$ref: "#/components/responses/BadRequest"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"403":
|
|
$ref: "#/components/responses/Forbidden"
|
|
|