Cloudflare Buckets API

openapi: 3.2.0
info:
  title: Cloudflare R2 Buckets 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/
servers:
- url: https://api.cloudflare.com/client/v4
  description: Cloudflare API v4 Production Server
security:
- bearerAuth: []
tags:
- name: Buckets
  description: Create, list, and delete R2 storage buckets.
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
components:
  schemas:
    BucketListResponse:
      type: object
      properties:
        result:
          type: object
          properties:
            buckets:
              type: array
              items:
                $ref: '#/components/schemas/Bucket'
          example: example_value
        success:
          type: boolean
          example: true
    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: []
  parameters:
    BucketName:
      name: bucket_name
      in: path
      required: true
      description: The name of the R2 bucket.
      schema:
        type: string
    AccountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the Cloudflare account.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token with R2 Storage permissions.
externalDocs:
  description: Cloudflare R2 API Documentation
  url: https://developers.cloudflare.com/r2/api/s3/api/