POST /api/users/multipart_upload_start/:file_id
Start a multipart upload

This endpoint provides a method to upload large media files in multiple parts, which may then be referenced in other API endpoints. To upload a file:

  1. Call this endpoint with a unique file_id (UUID) to identify the final file and the number of parts (part_count).
  2. The response includes an upload_id and presigned URLs for all parts.
  3. Upload each part to its corresponding presigned URL using a standard HTTP PUT request.
  4. After all parts are uploaded, call the complete endpoint with the upload_id and part ETags.
  5. Reference the uploaded file by file_id in other API endpoints.

Behavior

  • The file_id is a business-level identifier that will be used to reference the file in other parts of the system.
  • The upload_id is an AWS S3-specific identifier for tracking the multipart upload session.
  • part_count must be specified upfront and cannot be changed later.
  • content_type is validated against a mobile media allowlist. Invalid MIME types return 400 Bad Request.
  • Presigned URLs are provided for all parts specified in part_count.
  • Parts can be uploaded in any order - the part number is used to reconstruct the file in the correct order.
  • Parts can be uploaded in parallel for better performance.
  • Each part must be at least 5MB in size (except the last part).
  • Maximum part size is 5GB (5,120MB).
  • Maximum number of parts is 2000 (Record360 Imposed Limit).
  • The complete endpoint must be called with all parts’ ETags to finalize the upload.
  • If an upload fails, you can retry with the same file_id and upload_id.
  • Presigned URLs expire after 24 hours. The complete endpoint must be called before all URLs expire.

Examples

$ curl -i \
  -H 'Accept: application/json; version=1' \
  -H "Authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIisjQyLCJpYXQiOjE0NjM2OTQ4MjN9.k48v-R-un93KdIXqp9Zi12JOGJCu8uibtrWjscFCTqc" \
  https://api.record360.com/api/users/multipart_upload_start/new_file_42?part_count=3&content_type=video/mp4

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "new_file_42",
  "upload_id": "example-upload-id",
  "key": "users/42/new_file_42",
  "presigned_urls": [
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=1&uploadId=example-upload-id&...",
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=2&uploadId=example-upload-id&...",
    "https://bucket.s3.amazonaws.com/users/42/new_file_42?partNumber=3&uploadId=example-upload-id&..."
  ]
}

Params

Param name Description
file_id
required

UUID that will identify the final uploaded file. This is a business-level identifier that will be used to reference the file in other parts of the system.

Validations:

  • Must be a String
part_count
required

Number of parts the file will be split into. Must be between 1 and 20.

Validations:

  • Must be one of: String, Integer.
content_type
optional

MIME type of the file being uploaded. Must be one of the supported mobile media formats: image/jpeg, image/png, video/mp4, image/heif, image/heic, video/quicktime, image/webp, video/3gpp, video/webm, image/gif, video/x-m4v, image/bmp. If not provided, defaults to ‘application/octet-stream’. Case-insensitive.

Validations:

  • Must be a String