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.
| Field | Type | Required | Constraint |
|---|---|---|---|
| filename | string | Yes | 1 <= length |
| mimeType | string | Yes | 1 <= length |
| sizeBytes | integer | No | 0 <= value |
Exact source contract; origin modularized as {{API_BASE_URL}}
| Field | Type | Required |
|---|---|---|
| success | boolean | Yes |
| data | object | Yes |
| data.uploadUrl | string | Yes |
| data.publicUrl | string | Yes |
Exact source contract
| Status | Field | Type | Required | When it applies |
|---|---|---|---|---|
| 400 | success | boolean | Yes | Documented status; source does not define a specific trigger |
| 400 | message | string | Yes | Documented status; source does not define a specific trigger |
| 413 | success | boolean | Yes | Storage limit exceeded |
| 413 | message | string | Yes | Storage limit exceeded |
Exact source contract; 413 condition stated as storage limit exceeded; source does not define a specific 400 trigger
curl -X POST "{{API_BASE_URL}}/v1/media/upload" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"filename": "string",
"mimeType": "string"
}'{
"success": true,
"data": {
"uploadUrl": "string",
"publicUrl": "string"
}
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.filename | string | __1 | Yes | kind: schemaLength; value: 1 <= length | |
| body#1 | body.mimeType | string | __2 | Yes | kind: schemaLength; value: 1 <= length | |
| body#1 | body.sizeBytes | integer | __3 | No | kind: schemaRange; value: 0 <= value | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.data | object | __2 | Yes | ||
| response#2 | response.data.uploadUrl | string | __3 | Yes | ||
| response#2 | response.data.publicUrl | string | __4 | Yes | ||
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |