Update catalog maintenance configuration

POST/accounts/{account_id}/r2-catalog/{bucket_name}/maintenance-configs

Update the maintenance configuration for a catalog. This allows you to enable or disable compaction and adjust target file sizes for optimization.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Workers R2 Data Catalog Write

Path ParametersExpand Collapse

account_id: string

Use this to identify the account.

bucket_name: string

Specifies the R2 bucket name.

maxLength63

minLength3

Body ParametersJSONExpand Collapse

compaction: optional object { state, target_size_mb }

Updates compaction configuration (all fields optional).

state: optional "enabled" or "disabled"

Updates the state optionally.

One of the following:

"enabled"

"disabled"

target_size_mb: optional "64" or "128" or "256" or "512"

Updates the target file size optionally.

One of the following:

"64"

"128"

"256"

"512"

snapshot_expiration: optional object { max_snapshot_age, min_snapshots_to_keep, state }

Updates snapshot expiration configuration (all fields optional).

max_snapshot_age: optional string

Updates the maximum age for snapshots optionally.

min_snapshots_to_keep: optional number

Updates the minimum number of snapshots to retain optionally.

formatint64

minimum1

state: optional "enabled" or "disabled"

Updates the state optionally.

One of the following:

"enabled"

"disabled"

ReturnsExpand Collapse

errors: array of object { code, message }

Contains errors if the API call was unsuccessful.

code: number

Specifies the error code.

message: string

Describes the error.

messages: array of object { code, message }

Contains informational messages.

code: number

Specifies the message code.

message: string

Contains the message text.

success: boolean

Indicates whether the API call was successful.

result: optional object { compaction, snapshot_expiration }

Configures maintenance for the catalog.

compaction: optional object { state, target_size_mb }

Configures compaction for catalog maintenance.

state: "enabled" or "disabled"

Specifies the state of maintenance operations.

One of the following:

"enabled"

"disabled"

target_size_mb: "64" or "128" or "256" or "512"

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:

"64"

"128"

"256"

"512"

snapshot_expiration: optional object { max_snapshot_age, min_snapshots_to_keep, state }

Configures snapshot expiration settings.

max_snapshot_age: string

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: number

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64

minimum1

state: "enabled" or "disabled"

Specifies the state of maintenance operations.

One of the following:

"enabled"

"disabled"

Update catalog maintenance configuration

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/r2-catalog/$BUCKET_NAME/maintenance-configs \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{}'

{
  "errors": [],
  "messages": [],
  "result": {
    "compaction": {
      "state": "enabled",
      "target_size_mb": "256"
    },
    "snapshot_expiration": {
      "max_snapshot_age": "14d",
      "min_snapshots_to_keep": 5,
      "state": "enabled"
    }
  },
  "success": true
}

Returns Examples

{
  "errors": [],
  "messages": [],
  "result": {
    "compaction": {
      "state": "enabled",
      "target_size_mb": "256"
    },
    "snapshot_expiration": {
      "max_snapshot_age": "14d",
      "min_snapshots_to_keep": 5,
      "state": "enabled"
    }
  },
  "success": true
}