openapi: 3.1.0
info:
  title: Discourse API Documentation Admin Uploads API
  x-logo:
    url: https://docs.discourse.org/logo.svg
  version: latest
  description: 'This page contains the documentation on how to use Discourse through API calls.


    > Note: For any endpoints not listed you can follow the

    [reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)

    guide to figure out how to use an API endpoint.


    ### Request Content-Type


    The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,

    `multipart/form-data`, or `application/json`.


    ### Endpoint Names and Response Content-Type


    Most API endpoints provide the same content as their HTML counterparts. For example

    the URL `/categories` serves a list of categories, the `/categories.json` API provides the

    same information in JSON format.


    Instead of sending API requests to `/categories.json` you may also send them to `/categories`

    and add an `Accept: application/json` header to the request to get the JSON response.

    Sending requests with the `Accept` header is necessary if you want to use URLs

    for related endpoints returned by the API, such as pagination URLs.

    These URLs are returned without the `.json` prefix so you need to add the header in

    order to get the correct response format.


    ### Authentication


    Some endpoints do not require any authentication, pretty much anything else will

    require you to be authenticated.


    To become authenticated you will need to create an API Key from the admin panel.


    Once you have your API Key you can pass it in along with your API Username

    as an HTTP header like this:


    ```

    curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \

    -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \

    -H "Api-Username: system"

    ```


    and this is how POST requests will look:


    ```

    curl -X POST "http://127.0.0.1:3000/categories" \

    -H "Content-Type: multipart/form-data;" \

    -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \

    -H "Api-Username: system" \

    -F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \

    -F "color=49d9e9" \

    -F "text_color=f0fcfd"

    ```


    ### Boolean values


    If an endpoint accepts a boolean be sure to specify it as a lowercase

    `true` or `false` value unless noted otherwise.

    '
  license:
    name: MIT
    url: https://docs.discourse.org/LICENSE.txt
servers:
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: discourse.example.com
tags:
- name: Uploads
paths:
  /uploads.json:
    post:
      summary: Creates an upload
      tags:
      - Uploads
      operationId: createUpload
      parameters: []
      responses:
        '200':
          description: file uploaded
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  id:
                    type: integer
                  url:
                    type: string
                  original_filename:
                    type: string
                  filesize:
                    type: integer
                  width:
                    type: integer
                  height:
                    type: integer
                  thumbnail_width:
                    type: integer
                  thumbnail_height:
                    type: integer
                  extension:
                    type: string
                  short_url:
                    type: string
                  short_path:
                    type: string
                  retain_hours:
                    type:
                    - string
                    - 'null'
                  human_filesize:
                    type: string
                  dominant_color:
                    type:
                    - string
                    - 'null'
                  thumbnail:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      width:
                        type: integer
                      height:
                        type: integer
                      filesize:
                        type: integer
                  optimized_video:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      filesize:
                        type: integer
                      sha1:
                        type: string
                      original_filename:
                        type: string
                required:
                - id
                - url
                - original_filename
                - filesize
                - width
                - height
                - thumbnail_width
                - thumbnail_height
                - extension
                - short_url
                - short_path
                - retain_hours
                - human_filesize
      requestBody:
        content:
          multipart/form-data:
            schema:
              additionalProperties: false
              properties:
                type:
                  type: string
                  enum:
                  - avatar
                  - profile_background
                  - card_background
                  - custom_emoji
                  - composer
                user_id:
                  type: integer
                  description: required if uploading an avatar
                synchronous:
                  type: boolean
                  description: Use this flag to return an id and url
                file:
                  type: string
                  format: binary
              required:
              - type
  /uploads/generate-presigned-put.json:
    post:
      summary: Initiates a direct external upload
      tags:
      - Uploads
      operationId: generatePresignedPut
      description: 'Direct external uploads bypass the usual method of creating uploads

        via the POST /uploads route, and upload directly to an external provider,

        which by default is S3. This route begins the process, and will return

        a unique identifier for the external upload as well as a presigned URL

        which is where the file binary blob should be uploaded to.


        Once the upload is complete to the external service, you must call the

        POST /complete-external-upload route using the unique identifier returned

        by this route, which will create any required Upload record in the Discourse

        database and also move file from its temporary location to the final

        destination in the external storage service.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  key:
                    type: string
                    description: 'The path of the temporary file on the external storage

                      service.'
                    example: temp/site/uploads/default/12345/67890.jpg
                  url:
                    type: string
                    description: 'A presigned PUT URL which must be used to upload

                      the file binary blob to.'
                    example: https://file-uploads.s3.us-west-2.amazonaws.com/temp/site/uploads/default/123/456.jpg?x-amz-acl=private&x-amz-meta-sha1-checksum=sha1&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AAAAus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20211221T011246Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=12345678
                  signed_headers:
                    type: object
                    description: A map of headers that must be sent with the PUT request.
                    example:
                      x-amz-acl: private
                      x-amz-meta-sha1-checksum: sha1
                  unique_identifier:
                    type: string
                    description: 'A unique string that identifies the external upload.

                      This must be stored and then sent in the /complete-external-upload

                      endpoint to complete the direct upload.'
                    example: 66e86218-80d9-4bda-b4d5-2b6def968705
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                type:
                  type: string
                  enum:
                  - avatar
                  - profile_background
                  - card_background
                  - custom_emoji
                  - composer
                file_name:
                  type: string
                  example: IMG_2021.jpeg
                file_size:
                  type: integer
                  description: File size should be represented in bytes.
                  example: 4096
                metadata:
                  type: object
                  additionalProperties: false
                  properties:
                    sha1-checksum:
                      type: string
                      description: 'The SHA1 checksum of the upload binary blob. Optionally

                        be provided and serves as an additional security check when

                        later processing the file in complete-external-upload endpoint.'
              required:
              - type
              - file_name
              - file_size
  /uploads/complete-external-upload.json:
    post:
      summary: Completes a direct external upload
      tags:
      - Uploads
      operationId: completeExternalUpload
      description: 'Completes an external upload initialized with /get-presigned-put. The

        file will be moved from its temporary location in external storage to

        a final destination in the S3 bucket. An Upload record will also be

        created in the database in most cases.


        If a sha1-checksum was provided in the initial request it will also

        be compared with the uploaded file in storage to make sure the same

        file was uploaded. The file size will be compared for the same reason.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  id:
                    type: integer
                  url:
                    type: string
                  original_filename:
                    type: string
                  filesize:
                    type: integer
                  width:
                    type: integer
                  height:
                    type: integer
                  thumbnail_width:
                    type: integer
                  thumbnail_height:
                    type: integer
                  extension:
                    type: string
                  short_url:
                    type: string
                  short_path:
                    type: string
                  retain_hours:
                    type:
                    - string
                    - 'null'
                  human_filesize:
                    type: string
                  dominant_color:
                    type:
                    - string
                    - 'null'
                  thumbnail:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      width:
                        type: integer
                      height:
                        type: integer
                      filesize:
                        type: integer
                  optimized_video:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      filesize:
                        type: integer
                      sha1:
                        type: string
                      original_filename:
                        type: string
                required:
                - id
                - url
                - original_filename
                - filesize
                - width
                - height
                - thumbnail_width
                - thumbnail_height
                - extension
                - short_url
                - short_path
                - retain_hours
                - human_filesize
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                unique_identifier:
                  type: string
                  example: 66e86218-80d9-4bda-b4d5-2b6def968705
                  description: 'The unique identifier returned in the original /generate-presigned-put

                    request.'
                for_private_message:
                  type: string
                  example: 'true'
                  description: 'Optionally set this to true if the upload is for a

                    private message.'
                for_site_setting:
                  type: string
                  example: 'true'
                  description: 'Optionally set this to true if the upload is for a

                    site setting.'
                pasted:
                  type: string
                  example: 'true'
                  description: 'Optionally set this to true if the upload was pasted

                    into the upload area. This will convert PNG files to JPEG.'
              required:
              - unique_identifier
  /uploads/create-multipart.json:
    post:
      summary: Creates a multipart external upload
      tags:
      - Uploads
      operationId: createMultipartUpload
      description: 'Creates a multipart upload in the external storage provider, storing

        a temporary reference to the external upload similar to /get-presigned-put.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  key:
                    type: string
                    description: 'The path of the temporary file on the external storage

                      service.'
                    example: temp/site/uploads/default/12345/67890.jpg
                  external_upload_identifier:
                    type: string
                    description: 'The identifier of the multipart upload in the external

                      storage provider. This is the multipart upload_id in AWS S3.'
                    example: 84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ
                  unique_identifier:
                    type: string
                    description: 'A unique string that identifies the external upload.

                      This must be stored and then sent in the /complete-multipart

                      and /batch-presign-multipart-parts endpoints.'
                    example: 66e86218-80d9-4bda-b4d5-2b6def968705
                required:
                - external_upload_identifier
                - key
                - unique_identifier
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                upload_type:
                  type: string
                  enum:
                  - avatar
                  - profile_background
                  - card_background
                  - custom_emoji
                  - composer
                file_name:
                  type: string
                  example: IMG_2021.jpeg
                file_size:
                  type: integer
                  description: File size should be represented in bytes.
                  example: 4096
                metadata:
                  type: object
                  additionalProperties: false
                  properties:
                    sha1-checksum:
                      type: string
                      description: 'The SHA1 checksum of the upload binary blob. Optionally

                        be provided and serves as an additional security check when

                        later processing the file in complete-external-upload endpoint.'
              required:
              - upload_type
              - file_name
              - file_size
  /uploads/batch-presign-multipart-parts.json:
    post:
      summary: Generates batches of presigned URLs for multipart parts
      tags:
      - Uploads
      operationId: batchPresignMultipartParts
      description: 'Multipart uploads are uploaded in chunks or parts to individual presigned

        URLs, similar to the one generated by /generate-presigned-put. The part

        numbers provided must be between 1 and 10000. The total number of parts

        will depend on the chunk size in bytes that you intend to use to upload

        each chunk. For example a 12MB file may have 2 5MB chunks and a final

        2MB chunk, for part numbers 1, 2, and 3.


        This endpoint will return a presigned URL for each part number provided,

        which you can then use to send PUT requests for the binary chunk corresponding

        to that part. When the part is uploaded, the provider should return an

        ETag for the part, and this should be stored along with the part number,

        because this is needed to complete the multipart upload.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  presigned_urls:
                    type: object
                    description: 'The presigned URLs for each part number, which has

                      the part numbers as keys.'
                    example:
                      '1': https://discourse-martin-uploads-test.s3.us-east-2.amazonaws.com/temp/uploads/default/123abc/123abc.jpg?partNumber=1&uploadId=123456abcd&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test&X-Amz-Date=20211222T012336Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123
                required:
                - presigned_urls
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                part_numbers:
                  type: array
                  description: 'The part numbers to generate the presigned URLs for,

                    must be between 1 and 10000.'
                  example:
                  - 1
                  - 2
                  - 3
                unique_identifier:
                  type: string
                  description: 'The unique identifier returned in the original /create-multipart

                    request.'
                  example: 66e86218-80d9-4bda-b4d5-2b6def968705
              required:
              - part_numbers
              - unique_identifier
  /uploads/abort-multipart.json:
    post:
      summary: Abort multipart upload
      tags:
      - Uploads
      operationId: abortMultipart
      description: 'This endpoint aborts the multipart upload initiated with /create-multipart.

        This should be used when cancelling the upload. It does not matter if parts

        were already uploaded into the external storage provider.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  success:
                    type: string
                    example: OK
                required:
                - success
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                external_upload_identifier:
                  type: string
                  description: 'The identifier of the multipart upload in the external

                    storage provider. This is the multipart upload_id in AWS S3.'
                  example: 84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ
              required:
              - external_upload_identifier
  /uploads/complete-multipart.json:
    post:
      summary: Complete multipart upload
      tags:
      - Uploads
      operationId: completeMultipart
      description: 'Completes the multipart upload in the external store, and copies the

        file from its temporary location to its final location in the store.

        All of the parts must have been uploaded to the external storage provider.

        An Upload record will be completed in most cases once the file is copied

        to its final location.


        You must have the correct permissions and CORS settings configured in your

        external provider. We support AWS S3 as the default. See:


        https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.


        An external file store must be set up and `enable_direct_s3_uploads` must

        be set to true for this endpoint to function.


        '
      parameters: []
      responses:
        '200':
          description: external upload initialized
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  id:
                    type: integer
                  url:
                    type: string
                  original_filename:
                    type: string
                  filesize:
                    type: integer
                  width:
                    type: integer
                  height:
                    type: integer
                  thumbnail_width:
                    type: integer
                  thumbnail_height:
                    type: integer
                  extension:
                    type: string
                  short_url:
                    type: string
                  short_path:
                    type: string
                  retain_hours:
                    type:
                    - string
                    - 'null'
                  human_filesize:
                    type: string
                  dominant_color:
                    type:
                    - string
                    - 'null'
                  thumbnail:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      width:
                        type: integer
                      height:
                        type: integer
                      filesize:
                        type: integer
                  optimized_video:
                    type:
                    - object
                    - 'null'
                    additionalProperties: false
                    properties:
                      id:
                        type: integer
                      upload_id:
                        type: integer
                      url:
                        type: string
                      extension:
                        type: string
                      filesize:
                        type: integer
                      sha1:
                        type: string
                      original_filename:
                        type: string
                required:
                - id
                - url
                - original_filename
                - filesize
                - width
                - height
                - thumbnail_width
                - thumbnail_height
                - extension
                - short_url
                - short_path
                - retain_hours
                - human_filesize
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                unique_identifier:
                  type: string
                  example: 66e86218-80d9-4bda-b4d5-2b6def968705
                  description: 'The unique identifier returned in the original /create-multipart

                    request.'
                parts:
                  type: array
                  example:
                  - part_number: 1
                    etag: 0c376dcfcc2606f4335bbc732de93344
                  - part_number: 2
                    etag: 09ert8cfcc2606f4335bbc732de91122
                  description: 'All of the part numbers and their corresponding ETags

                    that have been uploaded must be provided.'
              required:
              - unique_identifier
              - parts