Cloudflare R2 R2 Catalog Management API
The R2 Catalog Management API from Cloudflare R2 — 4 operation(s) for r2 catalog management.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cloudflare-r2-r2-catalog-management-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cloudflare R2 Cloudflare R2 Catalog Management API
description: Cloudflare API endpoints for managing R2 object storage buckets, objects, CORS, lifecycle policies, custom domains, event notifications, data catalog, and temporary credentials.
version: 4.0.0
termsOfService: https://www.cloudflare.com/website-terms/
contact:
name: Cloudflare Developer Docs
url: https://developers.cloudflare.com/r2/
servers:
- url: https://api.cloudflare.com/client/v4
description: Cloudflare API v4
tags:
- name: R2 Catalog Management
paths:
/accounts/{account_id}/r2-catalog:
get:
description: 'Returns a list of R2 buckets that have been enabled as Apache Iceberg catalogs
for the specified account. Each catalog represents an R2 bucket configured
to store Iceberg metadata and data files.
'
operationId: list-catalogs
parameters:
- description: Identifies the account.
in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_account-id'
responses:
'200':
content:
application/json:
example:
errors: []
messages: []
result:
warehouses:
- bucket: analytics-bucket
id: 550e8400-e29b-41d4-a716-446655440000
maintenance_config:
compaction:
state: enabled
target_size_mb: '128'
snapshot_expiration:
max_snapshot_age: 7d
min_snapshots_to_keep: 100
state: enabled
name: account123_analytics-bucket
status: active
- bucket: logs-bucket
id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
maintenance_config:
compaction:
state: disabled
target_size_mb: '128'
snapshot_expiration:
max_snapshot_age: 7d
min_snapshots_to_keep: 100
state: disabled
name: account123_logs-bucket
status: inactive
success: true
schema:
allOf:
- $ref: '#/components/schemas/r2-data-catalog_api-response-single'
- properties:
result:
$ref: '#/components/schemas/r2-data-catalog_catalog-list'
type: object
description: List of R2 catalogs.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Bad request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Forbidden.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Internal server error.
security:
- api_token: []
- api_email: []
api_key: []
summary: List R2 catalogs
tags:
- R2 Catalog Management
x-api-token-group:
- Workers R2 Data Catalog Write
- Workers R2 Data Catalog Read
/accounts/{account_id}/r2-catalog/{bucket_name}:
get:
description: 'Retrieve detailed information about a specific R2 catalog by bucket name.
Returns catalog status, maintenance configuration, and credential status.
'
operationId: get-catalog-details
parameters:
- description: Identifies the account.
in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_account-id'
- description: Specifies the R2 bucket name.
in: path
name: bucket_name
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_bucket-name'
responses:
'200':
content:
application/json:
example:
errors: []
messages: []
result:
bucket: analytics-bucket
credential_status: present
id: 550e8400-e29b-41d4-a716-446655440000
maintenance_config:
compaction:
state: enabled
target_size_mb: '128'
snapshot_expiration:
max_snapshot_age: 7d
min_snapshots_to_keep: 100
state: enabled
name: account123_analytics-bucket
status: active
success: true
schema:
allOf:
- $ref: '#/components/schemas/r2-data-catalog_api-response-single'
- properties:
result:
$ref: '#/components/schemas/r2-data-catalog_catalog'
type: object
description: R2 catalog details.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Bad request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Forbidden.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Catalog not found.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Internal server error.
security:
- api_token: []
- api_email: []
api_key: []
summary: Get R2 catalog details
tags:
- R2 Catalog Management
x-api-token-group:
- Workers R2 Data Catalog Write
- Workers R2 Data Catalog Read
/accounts/{account_id}/r2-catalog/{bucket_name}/disable:
post:
description: 'Disable an R2 bucket as a catalog. This operation deactivates the catalog
but preserves existing metadata and data files. The catalog can be
re-enabled later.
'
operationId: disable-catalog
parameters:
- description: Identifies the account.
in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_account-id'
- description: Specifies the R2 bucket name to disable as catalog.
in: path
name: bucket_name
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_bucket-name'
responses:
'204':
description: Catalog disabled successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Bad request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Forbidden.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Catalog not found.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Internal server error.
security:
- api_token: []
- api_email: []
api_key: []
summary: Disable R2 catalog
tags:
- R2 Catalog Management
x-api-token-group:
- Workers R2 Data Catalog Write
/accounts/{account_id}/r2-catalog/{bucket_name}/enable:
post:
description: 'Enable an R2 bucket as an Apache Iceberg catalog. This operation creates
the necessary catalog infrastructure and activates the bucket for storing
Iceberg metadata and data files.
'
operationId: enable-catalog
parameters:
- description: Identifies the account.
in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_account-id'
- description: Specifies the R2 bucket name to enable as catalog.
in: path
name: bucket_name
required: true
schema:
$ref: '#/components/schemas/r2-data-catalog_bucket-name'
responses:
'200':
content:
application/json:
example:
errors: []
messages: []
result:
id: 550e8400-e29b-41d4-a716-446655440000
name: account123_my-bucket
success: true
schema:
allOf:
- $ref: '#/components/schemas/r2-data-catalog_api-response-single'
- properties:
result:
$ref: '#/components/schemas/r2-data-catalog_catalog-activation-response'
type: object
description: Catalog enabled successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Bad request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Authentication failed.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Forbidden.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: R2 bucket not found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Catalog already enabled.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/r2-data-catalog_api-response-common-failure'
description: Internal server error.
security:
- api_token: []
- api_email: []
api_key: []
summary: Enable R2 bucket as a catalog
tags:
- R2 Catalog Management
x-api-token-group:
- Workers R2 Data Catalog Write
components:
schemas:
r2-data-catalog_api-response-single:
properties:
errors:
$ref: '#/components/schemas/r2-data-catalog_api-response-errors'
messages:
$ref: '#/components/schemas/r2-data-catalog_api-response-messages'
success:
$ref: '#/components/schemas/r2-data-catalog_api-response-success'
required:
- success
- errors
- messages
type: object
r2-data-catalog_catalog-maintenance-state:
description: Specifies the state of maintenance operations.
enum:
- enabled
- disabled
example: enabled
type: string
r2-data-catalog_api-response-success:
description: Indicates whether the API call was successful.
example: true
type: boolean
r2-data-catalog_api-response-errors:
description: Contains errors if the API call was unsuccessful.
items:
properties:
code:
description: Specifies the error code.
type: integer
message:
description: Describes the error.
type: string
required:
- code
- message
type: object
type: array
r2-data-catalog_api-response-common-failure:
properties:
errors:
items:
properties:
code:
type: integer
message:
type: string
type: object
minItems: 1
type: array
messages:
items:
type: object
type: array
success:
enum:
- false
type: boolean
type: object
r2-data-catalog_account-id:
description: Use this to identify the account.
example: 0123456789abcdef0123456789abcdef
pattern: ^[a-fA-F0-9]{32}$
type: string
r2-data-catalog_snapshot-expiration-config:
description: Configures snapshot expiration settings.
properties:
max_snapshot_age:
description: 'Specifies the maximum age for snapshots. The system deletes snapshots older than this age.
Format: <number><unit> 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".
'
example: 7d
pattern: ^\d+(d|h|m|s)$
type: string
min_snapshots_to_keep:
description: Specifies the minimum number of snapshots to retain. Defaults to 100.
example: 100
format: int64
minimum: 1
type: integer
state:
$ref: '#/components/schemas/r2-data-catalog_catalog-maintenance-state'
required:
- state
- min_snapshots_to_keep
- max_snapshot_age
type: object
r2-data-catalog_catalog:
description: Contains R2 Data Catalog information.
properties:
bucket:
description: Specifies the associated R2 bucket name.
example: my-data-bucket
type: string
credential_status:
allOf:
- $ref: '#/components/schemas/r2-data-catalog_credential-status'
description: Shows the credential configuration status.
type:
- string
- 'null'
id:
description: Use this to uniquely identify the catalog.
example: 550e8400-e29b-41d4-a716-446655440000
format: uuid
type: string
maintenance_config:
allOf:
- $ref: '#/components/schemas/r2-data-catalog_catalog-maintenance-config'
description: Configures maintenance for the catalog.
type:
- object
- 'null'
name:
description: Specifies the catalog name (generated from account and bucket name).
example: account123_my-bucket
type: string
status:
$ref: '#/components/schemas/r2-data-catalog_catalog-status'
required:
- id
- name
- bucket
- status
type: object
r2-data-catalog_catalog-maintenance-config:
description: Configures maintenance for the catalog.
properties:
compaction:
$ref: '#/components/schemas/r2-data-catalog_catalog-compaction-config'
snapshot_expiration:
$ref: '#/components/schemas/r2-data-catalog_snapshot-expiration-config'
type: object
r2-data-catalog_catalog-list:
description: Contains the list of catalogs.
properties:
warehouses:
description: Lists catalogs in the account.
items:
$ref: '#/components/schemas/r2-data-catalog_catalog'
type: array
required:
- warehouses
type: object
r2-data-catalog_catalog-compaction-config:
description: Configures compaction for catalog maintenance.
properties:
state:
$ref: '#/components/schemas/r2-data-catalog_catalog-maintenance-state'
target_size_mb:
$ref: '#/components/schemas/r2-data-catalog_catalog-target-file-size'
required:
- state
- target_size_mb
type: object
r2-data-catalog_api-response-messages:
description: Contains informational messages.
items:
properties:
code:
description: Specifies the message code.
type: integer
message:
description: Contains the message text.
type: string
required:
- code
- message
type: object
type: array
r2-data-catalog_credential-status:
description: Shows the credential configuration status.
enum:
- present
- absent
example: present
type: string
r2-data-catalog_catalog-status:
description: Indicates the status of the catalog.
enum:
- active
- inactive
example: active
type: string
r2-data-catalog_catalog-activation-response:
description: Contains response from activating an R2 bucket as a catalog.
properties:
id:
description: Use this to uniquely identify the activated catalog.
example: 550e8400-e29b-41d4-a716-446655440000
format: uuid
type: string
name:
description: Specifies the name of the activated catalog.
example: account123_my-bucket
type: string
required:
- id
- name
type: object
r2-data-catalog_bucket-name:
description: Specifies the R2 bucket name.
example: my-data-bucket
maxLength: 63
minLength: 3
pattern: ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
type: string
r2-data-catalog_catalog-target-file-size:
description: Sets the target file size for compaction in megabytes. Defaults to "128".
enum:
- '64'
- '128'
- '256'
- '512'
example: '128'
type: string
securitySchemes:
api_email:
in: header
name: X-Auth-Email
type: apiKey
api_key:
in: header
name: X-Auth-Key
type: apiKey
api_token:
scheme: bearer
type: http
user_service_key:
in: header
name: X-Auth-User-Service-Key
type: apiKey