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