List Uploads

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Path Parameters

bucket_identifier

string

required

The unique identifier of the bucket

Query Parameters

limit

integer | null

offset

integer | null

Body

application/json

Request model for listing uploads with filtering, sorting, and search.

Provides flexible querying capabilities using the same filter/sort framework as documents, objects, and other list endpoints.

Supports: - Complex filters using LogicalOperator (AND, OR, NOT) - Shorthand filter syntax: {"metadata.campaign": "summer_2024"} - Full-text search across filename and metadata - Multi-field sorting - Pagination with limit/offset

Examples: - List all pending uploads in a bucket - Find uploads by metadata campaign - Search for uploads by filename pattern - Sort by file size or creation date

filters

LogicalOperator · object

Complex filters using logical operators (AND, OR, NOT). Supports shorthand syntax: pass field-value pairs for equality matching. Examples: - Filter by status: {'status': 'PENDING'} - Filter by metadata: {'metadata.campaign': 'summer_2024'} - Complex: {'AND': [{'field': 'status', 'operator': 'eq', 'value': 'PENDING'}, {'field': 'file_size_bytes', 'operator': 'gte', 'value': 1000000}]} See LogicalOperator documentation for full syntax.

Show child attributes

filters.AND

FilterCondition · object[] | null

Logical AND operation - all conditions must be true

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.AND.field

string

required

Field name to filter on

filters.AND.value

required

Value to compare against

Show child attributes

filters.AND.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.AND.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.AND.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "name",
    "operator": "eq",
    "value": "John"
  },
  {
    "field": "age",
    "operator": "gte",
    "value": 30
  }
]

filters.OR

FilterCondition · object[] | null

Logical OR operation - at least one condition must be true

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.OR.field

string

required

Field name to filter on

filters.OR.value

required

Value to compare against

Show child attributes

filters.OR.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.OR.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.OR.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "status",
    "operator": "eq",
    "value": "active"
  },
  {
    "field": "role",
    "operator": "eq",
    "value": "admin"
  }
]

filters.NOT

FilterCondition · object[] | null

Logical NOT operation - all conditions must be false

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.NOT.field

string

required

Field name to filter on

filters.NOT.value

required

Value to compare against

Show child attributes

filters.NOT.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.NOT.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.NOT.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "department",
    "operator": "eq",
    "value": "HR"
  },
  {
    "field": "location",
    "operator": "eq",
    "value": "remote"
  }
]

filters.case_sensitive

boolean | null

default:false

Whether to perform case-sensitive matching

Example:

true

Example:

{ "status": "PENDING" }

sort

SortOption · object

Sort options for ordering results. Can sort by any field including metadata fields using dot notation. Default: created_at descending (newest first). Examples: - Sort by creation date: {'field': 'created_at', 'direction': 'desc'} - Sort by file size: {'field': 'file_size_bytes', 'direction': 'asc'} - Sort by metadata: {'field': 'metadata.priority', 'direction': 'desc'}

Show child attributes

sort.field

string

required

Field to sort by, supports dot notation for nested fields

Example:

"created_at"

sort.direction

enum<string>

default:asc

Sort direction

Available options:

asc,

desc

Example:

"desc"

Example:

{
  "direction": "desc",
  "field": "created_at"
}

string | null

Full-text search across filename and metadata fields. Case-insensitive partial matching. Searches in: filename, metadata values (converted to strings). Examples: - 'video' - finds 'product_video.mp4', 'tutorial_video.mov' - 'summer' - finds uploads with metadata.campaign='summer_2024'

Example:

"video"

return_presigned_urls

boolean

default:false

Whether to regenerate presigned URLs for S3 access in the response. OPTIONAL, defaults to false. If true: - Generates new GET presigned URLs for completed uploads - Useful for downloading files from S3 - Adds ~50ms per upload to response time. If false: - No presigned URLs in response - Faster response time. Note: Original PUT presigned URLs are never returned (security).

limit

integer

default:20

Maximum number of uploads to return. OPTIONAL, defaults to 20.

Required range: 1 <= x <= 100

offset

integer

default:0

Number of uploads to skip for pagination. OPTIONAL, defaults to 0.

Required range: x >= 0

Response

Successful Response

Response model for listing uploads.

results

UploadResponse · object[]

required

List of upload records matching the query

Show child attributes

results.upload_id

string

required

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.

results.bucket_id

string

required

Target bucket ID where object will be created

results.filename

string

required

Name of the file to upload

results.content_type

string

required

MIME type enforced by the presigned URL

results.presigned_url_expiration

integer

required

How long the presigned URL is valid, in seconds

results.s3_key

string

required

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.

results.status

enum<string>

required

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

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

results.create_object_on_confirm

boolean

required

Whether bucket object will be auto-created on confirmation

results.created_at

string<date-time>

required

When this upload record was created (ISO 8601 format)

results.expires_at

string<date-time>

required

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)

results.file_size_bytes

integer | null

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

Example:

10485760

results.presigned_url

string<uri> | null

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).

Required string length: 1 - 2083

results.metadata

Metadata · object

Custom metadata for tracking

results.object_metadata

Object Metadata · object

Metadata for the bucket object (if create_object_on_confirm=true)

results.blob_property

string | null

Property name for the blob in bucket object

results.blob_type

string | null

Type of blob (IMAGE, VIDEO, etc.)

results.file_hash

string | null

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

Example:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

results.skip_duplicates

boolean

default:true

Whether duplicate detection was enabled for this upload

results.is_duplicate

boolean

default:false

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.

results.duplicate_of_upload_id

string | null

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.

Example:

"upl_original123"

results.message

string | null

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.'

results.completed_at

string<date-time> | null

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

Example:

"2024-01-15T10:35:00Z"

results.verified_at

string<date-time> | null

When S3 object existence was verified (ISO 8601 format)

Example:

"2024-01-15T10:35:00Z"

results.etag

string | null

S3 ETag from the uploaded object (set during confirmation)

Example:

"d41d8cd98f00b204e9800998ecf8427e"

results.object_id

string | null

Created bucket object ID (if create_object_on_confirm was true)

Example:

"obj_a1b2c3d4e5f6"

results.task_id

string | null

Celery task ID for async confirmation (if processed asynchronously)

Example:

"task_abc123"

pagination

PaginationResponse · object

required

Pagination metadata including total count, limit, offset, has_more

Show child attributes

pagination.total

integer

required

pagination.page

integer

required

pagination.page_size

integer

required

pagination.total_pages

integer

required

pagination.next_page

string | null

pagination.previous_page

string | null

stats

UploadListStats · object

required

Aggregate statistics across all uploads in the result

Show child attributes

stats.total_uploads

integer

required

Total number of uploads in the result set

stats.total_size_bytes

integer

required

Total size of all files in bytes

stats.uploads_by_status

Uploads By Status · object

required

Count of uploads grouped by status

Show child attributes

stats.uploads_by_status.{key}

integer

stats.avg_file_size_bytes

number

required

Average file size across all uploads

stats.unique_buckets

integer

required

Number of unique buckets in the result set

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Headers

Path Parameters

Query Parameters

Body

Response