Skip to content

presigned S3 upload URL API

Use this presigned S3 upload URL API when a client needs a direct upload destination for a media file before the file is referenced elsewhere. The operation is POST /v1/media/upload: send the file name and MIME type, receive an uploadUrl for the file transfer and a publicUrl to reuse after the upload, and handle the documented 400 and 413 responses instead of assuming every request succeeds.

Operation summary: request a presigned S3 URL, then upload the file

POST /v1/media/upload returns a presigned S3 URL to upload a media file. The intended sequence is to request the URL first, upload the file bytes to the returned uploadUrl, and then use the returned publicUrl as the reference to the stored file. Keeping those steps separate matters because the first call only creates the upload destination; it does not itself transfer the file content. If the upload to uploadUrl fails, retrying the upload step is different from requesting a new presigned S3 URL, and the client should not treat a successful URL request as proof that the file arrived.

Authorization with the x-access-key header

Send the access token in the x-access-key header on the request to /v1/media/upload. Keep the header name exactly as x-access-key and send the request as application/json, as shown in the request example titled Request a presigned S3 URL for a media upload. The source contract specifies this header name and token placeholder; it does not specify a separate authorization-failure status for this endpoint, so no such status is described here.

Request body field map: filename, mimeType and sizeBytes

The request body requires filename as a string with length at least 1 and mimeType as a string with length at least 1. The optional sizeBytes field is an integer with a value of 0 or greater. Provide sizeBytes when you need exact limit enforcement and want the file tracked in the media library and counted toward storage. Without sizeBytes, a request is turned away only if storage is already at or above the cap. Before sending, check that filename and mimeType are non-empty strings and that sizeBytes, when present, is a non-negative integer, because those checks align the body with the documented field constraints.

200 response field map: success, data, uploadUrl and publicUrl

A 200 response contains success as a boolean and data as an object. Inside data, uploadUrl is the required string to upload the file to and publicUrl is the required string identifying the stored file location. Check success and the presence of both uploadUrl and publicUrl before attempting the upload step, and store publicUrl for later use rather than reconstructing a file location from filename. The response example titled 200 response example shows the exact field shape.

Failure matrix for 400 and 413 responses

Both 400 and 413 responses use the same shape: success as a boolean and message as a string. Use the status code to decide the next step. For 400, the source documents the status and shape but does not define a specific trigger, so check the request against the documented filename, mimeType and sizeBytes constraints and review the message before retrying. For 413, treat the failure as a storage-limit problem rather than a malformed request: do not simply resend the same file, and instead reduce the stored media or address the storage limit before requesting another upload URL. The response example titled 400 and 413 response example shows the shared error shape, and the failure matrix below separates when each status applies.

Upload sequence and checks before retrying

Work through the flow in order: call POST /v1/media/upload with x-access-key, filename, mimeType and sizeBytes when exact enforcement is needed; on 200, upload the file to uploadUrl; then reuse publicUrl wherever the stored file is referenced. If the first call returns 400, review the body fields and the message and call again only after correcting anything that does not match the documented constraints. If it returns 413, address the storage limit first. If the upload to uploadUrl fails after a 200, diagnose that transfer separately and do not assume publicUrl points to a complete file until the upload step has succeeded.

Request body fields for POST /v1/media/upload
FieldTypeRequiredConstraint
filenamestringYes1 <= length
mimeTypestringYes1 <= length
sizeBytesintegerNo0 <= value

Exact source contract; origin modularized as {{API_BASE_URL}}

200 response fields
FieldTypeRequired
successbooleanYes
dataobjectYes
data.uploadUrlstringYes
data.publicUrlstringYes

Exact source contract

Failure matrix for 400 and 413 responses
StatusFieldTypeRequiredWhen it applies
400successbooleanYesDocumented status; source does not define a specific trigger
400messagestringYesDocumented status; source does not define a specific trigger
413successbooleanYesStorage limit exceeded
413messagestringYesStorage limit exceeded

Exact source contract; 413 condition stated as storage limit exceeded; source does not define a specific 400 trigger

Request a presigned S3 URL for a media upload
curl -X POST "{{API_BASE_URL}}/v1/media/upload" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "filename": "string",
    "mimeType": "string"
  }'
200 response example
{
  "success": true,
  "data": {
    "uploadUrl": "string",
    "publicUrl": "string"
  }
}
400 and 413 response example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.filenamestring__1Yeskind: schemaLength; value: 1 <= length
body#1body.mimeTypestring__2Yeskind: schemaLength; value: 1 <= length
body#1body.sizeBytesinteger__3Nokind: schemaRange; value: 0 <= value
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.dataobject__2Yes
response#2response.data.uploadUrlstring__3Yes
response#2response.data.publicUrlstring__4Yes
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes