Cloudflare R2 is S3-compatible object storage with zero egress fees. The R2 API allows developers to create and manage buckets, upload and retrieve objects, and configure access controls. R2 supports the S3 API for compatibility with existing tools and SDKs.
openapi: 3.1.0
info:
title: Cloudflare R2 API
description: >-
Cloudflare R2 is S3-compatible object storage with zero egress fees. The
R2 API allows developers to create and manage buckets, upload and retrieve
objects, and configure access controls. R2 supports the S3 API for
compatibility with existing tools and SDKs. This specification covers the
Cloudflare management API for R2 bucket administration.
version: '4.0'
contact:
name: Cloudflare Support
url: https://support.cloudflare.com/
termsOfService: https://www.cloudflare.com/terms/
externalDocs:
description: Cloudflare R2 API Documentation
url: https://developers.cloudflare.com/r2/api/s3/api/
servers:
- url: https://api.cloudflare.com/client/v4
description: Cloudflare API v4 Production Server
tags:
- name: Buckets
description: >-
Create, list, and delete R2 storage buckets.
- name: Configuration
description: >-
Configure bucket settings including CORS, lifecycle rules, and public access.
- name: Objects
description: >-
Upload, download, and manage objects within R2 buckets.
security:
- bearerAuth: []
paths:
/accounts/{account_id}/r2/buckets:
get:
operationId: listR2Buckets
summary: Cloudflare List R2 Buckets
description: >-
Returns a list of all R2 buckets for the account.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/AccountId'
- name: name_contains
in: query
description: Filter buckets by name substring.
schema:
type: string
example: example_value
- name: start_after
in: query
description: Bucket name to start listing after for pagination.
schema:
type: string
example: example_value
- name: per_page
in: query
description: Number of buckets per page.
schema:
type: integer
example: 10
- name: cursor
in: query
description: Cursor for pagination.
schema:
type: string
example: example_value
responses:
'200':
description: List of R2 buckets.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketListResponse'
examples:
Listr2buckets200Example:
summary: Default listR2Buckets 200 response
x-microcks-default: true
value:
result:
buckets:
- {}
success: true
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createR2Bucket
summary: Cloudflare Create R2 Bucket
description: >-
Create a new R2 storage bucket. Bucket names must be globally unique
and between 3 and 63 characters.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: The name of the bucket.
minLength: 3
maxLength: 63
locationHint:
type: string
description: >-
Hint for where to create the bucket. Must be a valid
Cloudflare location.
storageClass:
type: string
description: Default storage class for objects.
enum:
- Standard
- InfrequentAccess
examples:
Creater2bucketRequestExample:
summary: Default createR2Bucket request
x-microcks-default: true
value:
name: Example Title
locationHint: example_value
storageClass: Standard
responses:
'200':
description: Bucket created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketResponse'
examples:
Creater2bucket200Example:
summary: Default createR2Bucket 200 response
x-microcks-default: true
value:
result:
name: Example Title
creation_date: '2026-01-15T10:30:00Z'
location: example_value
storage_class: example_value
success: true
errors:
- {}
messages:
- {}
'400':
description: Bad request.
'401':
description: Unauthorized.
'409':
description: Bucket name already exists.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/r2/buckets/{bucket_name}:
get:
operationId: getR2Bucket
summary: Cloudflare Get R2 Bucket
description: >-
Retrieve details of a specific R2 bucket.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BucketName'
responses:
'200':
description: Bucket details.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketResponse'
examples:
Getr2bucket200Example:
summary: Default getR2Bucket 200 response
x-microcks-default: true
value:
result:
name: Example Title
creation_date: '2026-01-15T10:30:00Z'
location: example_value
storage_class: example_value
success: true
errors:
- {}
messages:
- {}
'401':
description: Unauthorized.
'404':
description: Bucket not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteR2Bucket
summary: Cloudflare Delete R2 Bucket
description: >-
Delete an R2 bucket. The bucket must be empty before it can be deleted.
tags:
- Buckets
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BucketName'
responses:
'200':
description: Bucket deleted successfully.
'401':
description: Unauthorized.
'404':
description: Bucket not found.
'409':
description: Bucket is not empty.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/r2/buckets/{bucket_name}/objects:
get:
operationId: listR2Objects
summary: Cloudflare List Objects in Bucket
description: >-
List objects stored in an R2 bucket with optional prefix filtering and
pagination.
tags:
- Objects
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BucketName'
- name: prefix
in: query
description: Filter objects by key prefix.
schema:
type: string
example: example_value
- name: delimiter
in: query
description: Delimiter for grouping object keys.
schema:
type: string
example: example_value
- name: cursor
in: query
description: Cursor for pagination.
schema:
type: string
example: example_value
- name: per_page
in: query
description: Number of objects per page.
schema:
type: integer
example: 10
responses:
'200':
description: List of objects.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/r2/buckets/{bucket_name}/configuration:
get:
operationId: getR2BucketConfiguration
summary: Cloudflare Get Bucket Configuration
description: >-
Retrieve the configuration settings for an R2 bucket including CORS
and lifecycle rules.
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BucketName'
responses:
'200':
description: Bucket configuration.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateR2BucketConfiguration
summary: Cloudflare Update Bucket Configuration
description: >-
Update configuration settings for an R2 bucket.
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/BucketName'
responses:
'200':
description: Configuration updated.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API token with R2 Storage permissions.
parameters:
AccountId:
name: account_id
in: path
required: true
description: The unique identifier of the Cloudflare account.
schema:
type: string
BucketName:
name: bucket_name
in: path
required: true
description: The name of the R2 bucket.
schema:
type: string
schemas:
Bucket:
type: object
properties:
name:
type: string
description: The name of the bucket.
example: Example Title
creation_date:
type: string
format: date-time
description: When the bucket was created.
example: '2026-01-15T10:30:00Z'
location:
type: string
description: The location of the bucket.
example: example_value
storage_class:
type: string
description: Default storage class for the bucket.
example: example_value
BucketResponse:
type: object
properties:
result:
$ref: '#/components/schemas/Bucket'
success:
type: boolean
example: true
errors:
type: array
items:
type: object
example: []
messages:
type: array
items:
type: object
example: []
BucketListResponse:
type: object
properties:
result:
type: object
properties:
buckets:
type: array
items:
$ref: '#/components/schemas/Bucket'
example: example_value
success:
type: boolean
example: true