Supabase Buckets API

openapi: 3.1.0
info:
  title: Supabase Auth Admin Buckets API
  description: The Supabase Auth API (based on GoTrue) is a JWT-based API for managing users and issuing access tokens. It provides endpoints for user signup, signin with email/password, magic links, one-time passwords, OAuth social login, token refresh, user management, multi-factor authentication, and SAML-based single sign-on. When deployed on Supabase, the server requires an apikey header containing a valid Supabase-issued API key.
  version: 2.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/auth/v1
  description: Supabase Project Auth Server
  variables:
    project_ref:
      description: Your Supabase project reference ID
      default: your-project-ref
security:
- apiKeyAuth: []
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 (anon key for public operations, service_role key for admin operations).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from a successful authentication.
externalDocs:
  description: Supabase Auth Documentation
  url: https://supabase.com/docs/guides/auth