Sign in

v3

latestOpenAPI 3.1.0MIT2026-07-31930688.4 KB
Uploads

Initiates a direct external upload

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.

post/uploads/generate-presigned-put.json

Request body

type'avatar' | 'profile_background' | 'card_background' | 'custom_emoji' | 'composer' required
file_namestring required
file_sizeinteger required

File size should be represented in bytes.

Example request

{
  "file_name": "IMG_2021.jpeg",
  "file_size": 4096
}

Response

external upload initialized

keystring

The path of the temporary file on the external storage service.

urlstring

A presigned PUT URL which must be used to upload the file binary blob to.

signed_headersobject

A map of headers that must be sent with the PUT request.

unique_identifierstring

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 response

{
  "key": "temp/site/uploads/default/12345/67890.jpg",
  "url": "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": {
    "x-amz-acl": "private",
    "x-amz-meta-sha1-checksum": "sha1"
  },
  "unique_identifier": "66e86218-80d9-4bda-b4d5-2b6def968705"
}