Create Upload

Name of the file to upload. REQUIRED. Must be a valid filename without path traversal characters (../, ). The filename is used to derive the blob_property if not explicitly provided. Examples: 'product_video.mp4', 'thumbnail.jpg', 'transcript.txt'

MIME type of the file. REQUIRED. Must be a valid MIME type (e.g., 'video/mp4', 'image/jpeg', 'application/pdf'). The presigned URL will enforce this content type during upload. Used to validate compatibility with bucket schema if create_object_on_confirm=true.

Expected file size in bytes. OPTIONAL but RECOMMENDED. If provided, will be validated against: 1. Tier-based file size limits (100MB free, 5GB pro, 50GB enterprise) 2. Storage quota availability 3. Actual uploaded file size during confirmation. If not provided, quota checking is skipped until confirmation.

How long the presigned URL is valid, in seconds. OPTIONAL, defaults to 3600 (1 hour). Valid range: 60 seconds (1 minute) to 86400 seconds (24 hours). After expiration, the URL cannot be used and you must request a new one. Recommendation: Use shorter expiration (300-900 seconds) for security-sensitive files, longer expiration (3600-7200 seconds) for large files that take time to upload.

Custom metadata for tracking purposes. OPTIONAL. Stored with the upload record for filtering and analytics. Does NOT affect the created bucket object (use object_metadata for that). Common uses: campaign tracking, user identification, upload source.

Whether to automatically create a bucket object when upload is confirmed. OPTIONAL, defaults to false. If true: - Bucket MUST have a schema defined - blob_property must exist in bucket schema - content_type must match schema field type - Validation happens BEFORE generating presigned URL. If false: - Upload is confirmed but no object is created - You can manually create the object later using the S3 URL.

Metadata to attach to the created bucket object. OPTIONAL. Only used if create_object_on_confirm=true. This metadata will be: 1. Validated against bucket schema (if keys match schema fields) 2. Attached to the bucket object 3. Passed to downstream documents in connected collections. Example: {'priority': 'high', 'category': 'products', 'tags': ['featured']}

Property name for the blob in the bucket object. OPTIONAL. Defaults to filename without extension (e.g., 'product_video.mp4' → 'product_video'). If create_object_on_confirm=true: - Must exist in bucket schema - Must be alphanumeric with underscores only - Will be validated BEFORE generating presigned URL. Common values: 'video', 'image', 'thumbnail', 'transcript', 'content'.

Type of blob. OPTIONAL. Defaults to type derived from content_type (e.g., 'video/mp4' → 'VIDEO'). Must be a valid BucketSchemaFieldType if provided. Valid values: IMAGE, VIDEO, AUDIO, TEXT, PDF, DOCUMENT, etc. If create_object_on_confirm=true, will be validated against bucket schema field type.

SHA256 hash of the file content for duplicate detection. OPTIONAL. If provided: - System checks for existing confirmed uploads with same hash - If duplicate found and skip_duplicates=true, returns existing upload - Hash will be validated against actual S3 ETag during confirmation. If not provided: - Hash is calculated from S3 ETag after upload - Duplicate detection only happens during confirmation. Use case: Pre-calculate hash client-side to avoid uploading duplicates. Format: 64-character hexadecimal string (SHA256).

Skip upload if a file with the same hash already exists. OPTIONAL, defaults to TRUE. If true (default): - If file_hash provided: System checks MongoDB for existing completed upload with same hash - If duplicate found: Returns existing upload details WITHOUT generating new presigned URL - If file_hash NOT provided: Duplicate check happens during confirmation using S3 ETag - Saves bandwidth, storage, and upload time by reusing existing files. If false: - Always generates new presigned URL even if file already uploaded - Creates separate upload record for same file content - Useful when you need distinct upload tracking for identical files. Recommendation: Keep default (true) unless you specifically need multiple upload records for same file.

Unique identifier for this upload. Auto-generated.

Use this ID to: - Check status: GET /v1/uploads/{upload_id} - Confirm upload: POST /v1/uploads/{upload_id}/confirm - Cancel upload: DELETE /v1/uploads/{upload_id} - Reference in object creation: POST /v1/buckets/{bucket_id}/objects with 'upload_id' in blobs

⚠️ ADVANCED: Reference upload_id in object creation to: - Combine multiple uploads into one object - Upload files in parallel, create object later - Reuse same upload across multiple objects

Example: POST /v1/buckets/{id}/objects { 'blobs': [{'property': 'video', 'type': 'VIDEO', 'upload_id': 'upl_abc123'}] }

Format: 'upl_' followed by 12 random characters.

Target bucket ID where object will be created

Name of the file to upload

MIME type enforced by the presigned URL

How long the presigned URL is valid, in seconds

Full S3 object key where the file will be stored. Format: {internal_id}/{namespace_id}/api_buckets_uploads_create/{upload_id}/{filename}. Used internally for verification and object creation.

Current upload status. After creation, always PENDING. Possible statuses: PENDING → IN_PROGRESS → PROCESSING → COMPLETED/FAILED/CANCELED

Whether bucket object will be auto-created on confirmation

When this upload record was created (ISO 8601 format)

When the presigned URL expires (ISO 8601 format). After this time: - The presigned URL cannot be used - Upload status will be marked as FAILED if not completed - The upload record will be auto-deleted 30 days later (MongoDB TTL)

Expected file size in bytes if provided in request. Will be validated during confirmation.

Time-limited HTTPS URL for uploading directly to S3. Use HTTP PUT with the file content to upload: curl -X PUT '{presigned_url}' -H 'Content-Type: {content_type}' --upload-file {filename} The URL includes authentication and expires after presigned_url_expiration seconds. After successful upload, S3 returns an ETag header - save this for confirmation. NOTE: This will be null if is_duplicate=true (duplicate found, no upload needed).

Custom metadata for tracking

Metadata for the bucket object (if create_object_on_confirm=true)

Property name for the blob in bucket object

Type of blob (IMAGE, VIDEO, etc.)

SHA256 hash of the file content. Set during confirmation from S3 metadata or provided in request. Used for duplicate detection.

Whether duplicate detection was enabled for this upload

Whether this upload was identified as a duplicate of an existing file. If true: - duplicate_of_upload_id contains the original upload - presigned_url will be null (no upload needed) - You can use the original upload's S3 object. This saves bandwidth and storage costs.

If skip_duplicates=true and duplicate found, this is the original upload_id. The response will reference the existing upload instead of creating a new one.

Human-readable message about the upload. Provided when is_duplicate=true or other special conditions. Example: 'File already exists with the same content hash. No upload needed - returning existing upload.'

When the upload was completed and verified (ISO 8601 format)

When S3 object existence was verified (ISO 8601 format)

S3 ETag from the uploaded object (set during confirmation)

Created bucket object ID (if create_object_on_confirm was true)

Celery task ID for async confirmation (if processed asynchronously)