> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Confirm Upload > Verify S3 upload completion and create bucket object. After uploading to S3 using the presigned URL, call this endpoint to: 1. Verify the file exists in S3 2. Validate ETag and file size (if provided) 3. Create bucket object (default, unless create_object_on_confirm=false) 4. Update upload status to COMPLETED **Sync vs Async**: - Files < 100MB: Processed synchronously (~100ms) - Files >= 100MB or async=true: Processed asynchronously (returns task_id) **Duplicate Detection**: - If file hash matches existing upload, marks as duplicate - References original object_id if available ## OpenAPI ````yaml post /v1/buckets/{bucket_identifier}/uploads/{upload_id}/confirm openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/buckets/{bucket_identifier}/uploads/{upload_id}/confirm: post: tags: - Bucket Uploads summary: Confirm Upload description: |- Verify S3 upload completion and create bucket object. After uploading to S3 using the presigned URL, call this endpoint to: 1. Verify the file exists in S3 2. Validate ETag and file size (if provided) 3. Create bucket object (default, unless create_object_on_confirm=false) 4. Update upload status to COMPLETED **Sync vs Async**: - Files < 100MB: Processed synchronously (~100ms) - Files >= 100MB or async=true: Processed asynchronously (returns task_id) **Duplicate Detection**: - If file hash matches existing upload, marks as duplicate - References original object_id if available operationId: >- confirm_upload_v1_buckets__bucket_identifier__uploads__upload_id__confirm_post parameters: - name: bucket_identifier in: path required: true schema: type: string description: The unique identifier of the bucket title: Bucket Identifier description: The unique identifier of the bucket - name: upload_id in: path required: true schema: type: string description: The unique identifier of the upload title: Upload Id description: The unique identifier of the upload - name: async in: query required: false schema: type: boolean description: >- Process confirmation asynchronously (recommended for files >= 100MB) default: false title: Async description: Process confirmation asynchronously (recommended for files >= 100MB) requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/ConfirmUploadRequest' - type: 'null' title: Confirm Request responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConfirmUploadResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ConfirmUploadRequest: properties: etag: anyOf: - type: string - type: 'null' title: Etag description: >- S3 ETag returned from the upload. OPTIONAL but RECOMMENDED. After uploading to S3, the response includes an ETag header. Providing this ensures the file wasn't corrupted during upload. If provided and doesn't match S3's ETag, confirmation will fail with error. Format: Usually an MD5 hash, may be enclosed in quotes. examples: - d41d8cd98f00b204e9800998ecf8427e - '"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"' file_size_bytes: anyOf: - type: integer minimum: 1 - type: 'null' title: File Size Bytes description: >- Actual file size uploaded, in bytes. OPTIONAL but RECOMMENDED. If provided, will be validated against the actual S3 object size. Mismatch indicates upload corruption or network issues. If not provided, size validation is skipped. examples: - 10485760 - 52428800 auto_submit_batch: type: boolean title: Auto Submit Batch description: >- If true, automatically create AND submit a batch containing the newly created object after confirmation. The returned ``task_id`` will be the submitted batch's task id, and ``batch_id`` will be populated. Eliminates the need for separate POST /batches and POST /batches/{id}/submit calls during bulk ingest. Has no effect if ``create_object_on_confirm`` is false or the object is a duplicate. Defaults to false for backwards compatibility — existing flows that batch many objects into one submission still work. default: false type: object title: ConfirmUploadRequest description: >- Request to confirm S3 upload completion and create bucket object. ⚠️ THIS ENDPOINT IS REQUIRED AFTER UPLOADING TO S3! S3 presigned URLs have no callback mechanism - the API cannot detect when your upload completes. You MUST call this endpoint to finalize the upload. Why confirmation is required: - S3 doesn't notify us when uploads complete - We need to verify the file actually exists in S3 - We need to create the bucket object - We need to update quotas and tracking The system will: 1. Verify the S3 object exists (HeadObject call) 2. Validate ETag matches (if provided) - RECOMMENDED for integrity 3. Validate file size matches (if provided) 4. Create bucket object (default, unless create_object_on_confirm=false) 5. Update upload status to COMPLETED If you don't call confirm: - Upload stays in PENDING status - No bucket object is created - File is orphaned in S3 examples: - description: Confirm with ETag for integrity verification (recommended) etag: d41d8cd98f00b204e9800998ecf8427e file_size_bytes: 52428800 - description: Confirm with size only file_size_bytes: 10485760 - auto_submit_batch: true description: Auto-submit a batch after confirm (one-shot ingest) etag: d41d8cd98f00b204e9800998ecf8427e file_size_bytes: 52428800 - description: Basic confirmation without validation (not recommended) ConfirmUploadResponse: properties: upload_id: type: string title: Upload Id description: Upload ID that was confirmed status: $ref: '#/components/schemas/TaskStatusEnum' description: Updated upload status (COMPLETED or PROCESSING) etag: anyOf: - type: string - type: 'null' title: Etag description: S3 ETag from uploaded object file_size_bytes: anyOf: - type: integer - type: 'null' title: File Size Bytes description: Actual file size from S3 file_hash: anyOf: - type: string - type: 'null' title: File Hash description: File content hash (from ETag) verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When verification completed completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When upload completed object_id: anyOf: - type: string - type: 'null' title: Object Id description: Created bucket object ID (if create_object_on_confirm was true) task_id: anyOf: - type: string - type: 'null' title: Task Id description: >- Task ID for async processing. Populated when auto_submit_batch=true (holds the submitted batch's first-tier task id) or when async=true. batch_id: anyOf: - type: string - type: 'null' title: Batch Id description: >- Batch ID created and submitted by auto_submit_batch=true. Use it to poll status via GET /v1/buckets/{id}/batches/{batch_id}. message: anyOf: - type: string - type: 'null' title: Message description: Confirmation message type: object required: - upload_id - status title: ConfirmUploadResponse description: Response from upload confirmation. examples: - completed_at: '2024-01-15T10:35:00Z' description: Synchronous confirmation with object creation etag: d41d8cd98f00b204e9800998ecf8427e file_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 file_size_bytes: 52428800 object_id: obj_xyz789 status: COMPLETED upload_id: upl_abc123 verified_at: '2024-01-15T10:35:00Z' - description: Asynchronous confirmation message: Upload confirmation is being processed in the background. status: PROCESSING task_id: task_xyz789 upload_id: upl_abc123 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskStatusEnum: type: string enum: - PENDING - QUEUED - IN_PROGRESS - PROCESSING - COMPLETED - COMPLETED_WITH_ERRORS - FAILED - CANCELED - INTERRUPTED - UNKNOWN - SKIPPED - DRAFT - ACTIVE - ARCHIVED - SUSPENDED title: TaskStatusEnum description: |- Enumeration of task statuses for tracking asynchronous operations. Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution. Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces) Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted ACTIVE: Entity is active and operational (for buckets, collections, etc.) ARCHIVED: Entity has been archived SUSPENDED: Entity has been temporarily suspended Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state. Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately. Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ````