openapi: 3.2.0
info:
  title: Supabase Storage Buckets API
  description: The Supabase Storage API enables developers to store, organize, and serve large files such as images, videos, and documents. It provides bucket-based organization with support for uploading, downloading, and transforming files including on-the-fly image resizing and optimization. Access control is managed through Row Level Security policies tied to the PostgreSQL database. The API supports both public and private storage buckets, resumable uploads via the TUS protocol, and S3-compatible access.
  version: 1.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/storage/v1
  description: Supabase Project Storage Server
  variables:
    project_ref:
      description: Your Supabase project reference ID
      default: your-project-ref
security:
- apiKeyAuth: []
  bearerAuth: []
tags:
- name: Buckets
  description: Manage storage buckets that organize files and folders. Buckets can be public or private and have configurable file size limits and allowed MIME types.
paths:
  /bucket:
    get:
      operationId: listBuckets
      summary: List all buckets
      description: Returns a list of all storage buckets in the project. Requires authenticated access with appropriate permissions.
      tags:
      - Buckets
      responses:
        '200':
          description: Successfully retrieved buckets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bucket'
        '401':
          description: Unauthorized
    post:
      operationId: createBucket
      summary: Create a new bucket
      description: Creates a new storage bucket with the specified configuration. Bucket names must be unique within a project and follow URL-safe naming conventions.
      tags:
      - Buckets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBucketRequest'
      responses:
        '200':
          description: Bucket created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the created bucket
        '400':
          description: Bad request - invalid bucket name or configuration
        '401':
          description: Unauthorized
  /bucket/{bucketId}:
    get:
      operationId: getBucket
      summary: Get bucket details
      description: Retrieves details about a specific storage bucket including its configuration, visibility, and file size limits.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketId'
      responses:
        '200':
          description: Successfully retrieved bucket details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '401':
          description: Unauthorized
        '404':
          description: Bucket not found
    put:
      operationId: updateBucket
      summary: Update a bucket
      description: Updates the configuration of an existing storage bucket including its visibility, file size limits, and allowed MIME types.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBucketRequest'
      responses:
        '200':
          description: Bucket updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
        '401':
          description: Unauthorized
        '404':
          description: Bucket not found
    delete:
      operationId: deleteBucket
      summary: Delete a bucket
      description: Deletes an empty storage bucket. The bucket must be emptied of all objects before deletion.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketId'
      responses:
        '200':
          description: Bucket deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Bucket not found
        '409':
          description: Conflict - bucket is not empty
  /bucket/{bucketId}/empty:
    post:
      operationId: emptyBucket
      summary: Empty a bucket
      description: Removes all objects from a storage bucket without deleting the bucket itself.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/BucketId'
      responses:
        '200':
          description: Bucket emptied successfully
        '401':
          description: Unauthorized
        '404':
          description: Bucket not found
components:
  parameters:
    BucketId:
      name: bucketId
      in: path
      required: true
      description: Unique identifier or name of the storage bucket
      schema:
        type: string
  schemas:
    UpdateBucketRequest:
      type: object
      properties:
        public:
          type: boolean
          description: Whether the bucket should be publicly accessible
        file_size_limit:
          type: integer
          description: Maximum file size in bytes
        allowed_mime_types:
          type: array
          items:
            type: string
          description: Allowed MIME types for uploads
    Bucket:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the bucket
        name:
          type: string
          description: Name of the bucket
        owner:
          type: string
          format: uuid
          description: UUID of the bucket owner
        public:
          type: boolean
          description: Whether the bucket is publicly accessible
        file_size_limit:
          type: integer
          description: Maximum file size allowed in bytes
        allowed_mime_types:
          type: array
          items:
            type: string
          description: List of allowed MIME types for uploads
        created_at:
          type: string
          format: date-time
          description: Timestamp when the bucket was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the bucket was last updated
    CreateBucketRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name for the new bucket
        id:
          type: string
          description: Optional custom ID (defaults to name)
        public:
          type: boolean
          description: Whether the bucket should be publicly accessible
          default: false
        file_size_limit:
          type: integer
          description: Maximum file size in bytes
        allowed_mime_types:
          type: array
          items:
            type: string
          description: Allowed MIME types for uploads
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Supabase project API key for request authorization.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token for authenticated operations.
externalDocs:
  description: Supabase Storage Documentation
  url: https://supabase.com/docs/guides/storage