240db4e2a7
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
589 lines
19 KiB
YAML
589 lines
19 KiB
YAML
/api/v4/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"
|
|
"/api/v4/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"
|
|
"/api/v4/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"
|
|
"/api/v4/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"
|
|
"/api/v4/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"
|
|
"/api/v4/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"
|
|
|
|
"/api/v4/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"
|
|
"/api/v4/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"
|
|
|