Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Bucket Uploads

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
post/v1/buckets/{bucket_identifier}/uploads/{upload_id}/confirm

Path parameters

bucket_identifierstring required

The unique identifier of the bucket

The unique identifier of the bucket

upload_idstring required

The unique identifier of the upload

The unique identifier of the upload

Query parameters

asyncboolean

Process confirmation asynchronously (recommended for files >= 100MB)

Process confirmation asynchronously (recommended for files >= 100MB)

Request body

etagstring nullable

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.

file_size_bytesinteger nullable

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.

auto_submit_batchboolean

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.

Example request

{
  "description": "Confirm with ETag for integrity verification (recommended)",
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "file_size_bytes": 52428800
}

Response

Successful Response

upload_idstring required

Upload ID that was confirmed

status'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' required

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

etagstring nullable

S3 ETag from uploaded object

file_size_bytesinteger nullable

Actual file size from S3

file_hashstring nullable

File content hash (from ETag)

verified_atstring date-time nullable

When verification completed

completed_atstring date-time nullable

When upload completed

object_idstring nullable

Created bucket object ID (if create_object_on_confirm was true)

task_idstring nullable

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_idstring nullable

Batch ID created and submitted by auto_submit_batch=true. Use it to poll status via GET /v1/buckets/{id}/batches/{batch_id}.

messagestring nullable

Confirmation message

Example response

{
  "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"
}