Bucket Objects

List Objects

Changed on

This endpoint lists objects in a bucket with cursor-based pagination, filtering, and sorting. Filtering, sorting and field selection go in the JSON request body. Pagination goes in the query string. A body key this endpoint does not read is rejected with a 422.

**Filtering**: `filters` in the body takes a logical operator tree. Use dot notation for
metadata fields (for example `metadata.type`).

**Sorting**: `sort` in the body is one object with a field and a direction
- Example: {"sort": {"field": "created_at", "direction": "desc"}}
- Direction: asc (ascending) or desc (descending), defaults to asc
- Without `sort`, objects come back in creation order, oldest first

**Pagination**: Cursor-based for efficient deep pagination
- First page: ?limit=100 (omit cursor)
- Next pages: ?limit=100&cursor={next_cursor}
- Use next_cursor from response to navigate
- No limit on pagination depth

**Total Count**: Optional (expensive operation)
- Use ?include_total=true to get total count
- Adds 50-200ms to response time
- Returns total, page, page_size, total_pages fields in pagination response
post/v1/buckets/{bucket_identifier}/objects/list

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/list
  • Auth: HTTP bearer and API key in header X-Namespace

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

Query parameters

limitinteger nullable
page_sizeinteger nullable
offsetinteger nullable
pageinteger nullable
cursorstring nullable
next_cursorstring nullable
afterstring nullable
include_totalboolean

Request body

searchstring nullable

Search term to filter objects by key or metadata

selectstring[] nullable

OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'status'). When specified, only the selected fields will be returned in the object results, reducing response size. System fields like 'object_id' and 'bucket_id' are always included. Use this to optimize response size when working with large objects.

return_presigned_urlsboolean nullable

Generate fresh presigned download URLs for all blobs with S3 storage. When true, each blob will include a 'presigned_url' in its properties. URLs expire after 1 hour.

Example request

{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at"
  },
  "select": [
    "metadata",
    "status",
    "created_at"
  ]
}

Response

Successful Response

Example response

{
  "pagination": {
    "has_more": false,
    "limit": 10,
    "skip": 0
  },
  "results": [
    {
      "blobs": [],
      "bucket_id": "bkt_9xy8z7",
      "created_at": "2024-10-21T10:30:00Z",
      "key_prefix": "/contract-2024",
      "metadata": {
        "category": "contracts",
        "year": 2024
      },
      "object_id": "obj_123abc456def",
      "status": "PENDING",
      "updated_at": "2024-10-21T10:30:00Z"
    }
  ]
}

Changes

  • d4b5fad18960Revision changes
    • info

      the response's property default value changed from DRAFT to PENDING for the status

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status