mostlymatter/api/v4/source/uploads.yaml

  "/api/v4/uploads":
    post:
      tags:
        - uploads
      summary: Create an upload
      description: >
        Creates a new upload session.


        __Minimum server version__: 5.28

        ##### Permissions

        Must have `upload_file` permission.

      operationId: CreateUpload
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - channel_id
                - filename
                - file_size
              properties:
                channel_id:
                  description: The ID of the channel to upload to.
                  type: string
                filename:
                  description: The name of the file to upload.
                  type: string
                file_size:
                  description: The size of the file to upload in bytes.
                  type: integer
                  format: int64
        required: true
      responses:
        "201":
          description: Upload creation successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadSession"
        "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"
      x-code-samples:
        - lang: Go
          source: >
            import "github.com/mattermost/mattermost-server/v5/model"


            Client := model.NewAPIv4Client("https://your-mattermost-url.com")

            Client.Login("email@domain.com", "Password1")

            us := &model.UploadSession{
              ChannelId: "4i6jn8r483nnuqnibnmgz8jo4o",
              Filename: "file.png",
              FileSize: 512000,
            }

            us, response := Client.CreateUpload(us)
        - lang: Curl
          source: |
            curl 'http://localhost:8065/api/v4/uploads' \                                                                                                          
            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' \
            -H 'Content-Type: application/json' \
            --data-binary '{"channel_id": "4i6jn8r483nnuqnibnmgz8jo4o", "filename": "test.png", "file_size": 512000}'
  "/api/v4/uploads/{upload_id}":
    get:
      tags:
        - uploads
      summary: Get an upload session
      description: |
        Gets an upload session that has been previously created.

        ##### Permissions
        Must be logged in as the user who created the upload session.
      operationId: GetUpload
      parameters:
        - name: upload_id
          in: path
          description: The ID of the upload session 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"
      x-code-samples:
        - lang: Go
          source: >
            import "github.com/mattermost/mattermost-server/v5/model"


            Client := model.NewAPIv4Client("https://your-mattermost-url.com")

            Client.Login("email@domain.com", "Password1")

            us, response := Client.GetUpload("nuyrh9ymridqmenof7exe3a6aw")
        - lang: Curl
          source: |
            curl 'http://localhost:8065/api/v4/uploads/nuyrh9ymridqmenof7exe3a6aw' \                                                                                            
            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw'
    post:
      tags:
        - uploads
      summary: Perform a file upload
      description: |
        Starts or resumes a file upload.  
        To resume an existing (incomplete) upload, data should be sent starting from the offset specified in the upload session object.

        The request body can be in one of two formats:
        - Binary file content streamed in request's body
        - multipart/form-data

        ##### Permissions
        Must be logged in as the user who created the upload session.
      operationId: UploadData
      parameters:
        - name: upload_id
          in: path
          description: The ID of the upload session the data belongs to.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
      responses:
        "201":
          description: Upload successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileInfo"
        "204":
          description: Upload incomplete
        "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"
      x-code-samples:
        - lang: Go
          source: >
            import (
              "os"

              "github.com/mattermost/mattermost-server/v5/model"
            )

            Client := model.NewAPIv4Client("https://your-mattermost-url.com")
            Client.Login("email@domain.com", "Password1")

            file, err := os.Open("file.png")
            if err != nil {
              fmt.Fprintf(os.Stderr, "%v\n", err)
              return
            }

            info, err := Client.UploadData(us, file)
        - lang: Curl
          source: |
            # Binary file content in request's body
            curl -X POST 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \
            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' --data-binary @file.png

            # multipart/form-data upload
            curl 'http://localhost:8065/api/v4/uploads/qyxbzmprrjbdpdaprsxm98m6qe' \
            -H 'Authorization: Bearer 9kg8nqrnxprd9jbykqeg4r51hw' -F data=@file.png