Supabase Objects API

openapi: 3.2.0
info:
  title: Supabase Storage Objects 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: Objects
  description: Upload, download, move, copy, and delete files within storage buckets.
paths:
  /object/{bucketName}/{objectPath}:
    post:
      operationId: uploadObject
      summary: Upload a file
      description: Uploads a file to the specified path within a bucket. If a file already exists at the path, the upload will fail unless the upsert option is used. Supports standard uploads and multipart form data.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      - name: x-upsert
        in: header
        schema:
          type: boolean
          default: false
        description: Whether to overwrite an existing file at the same path
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                cacheControl:
                  type: string
                  description: Cache-Control header value for the uploaded file
                  default: '3600'
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          description: Bad request - invalid file or path
        '401':
          description: Unauthorized
        '409':
          description: Conflict - file already exists (use upsert)
    put:
      operationId: updateObject
      summary: Update (replace) a file
      description: Replaces an existing file at the specified path with new content. The file must already exist.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The replacement file
                cacheControl:
                  type: string
                  description: Cache-Control header value
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '401':
          description: Unauthorized
        '404':
          description: File not found
    delete:
      operationId: deleteObject
      summary: Delete a file
      description: Permanently deletes a file at the specified path within a bucket.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      responses:
        '200':
          description: File deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /object/authenticated/{bucketName}/{objectPath}:
    get:
      operationId: downloadAuthenticatedObject
      summary: Download a private file
      description: Downloads a file from a private bucket. Requires authentication and appropriate Row Level Security permissions.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /object/public/{bucketName}/{objectPath}:
    get:
      operationId: downloadPublicObject
      summary: Download a public file
      description: Downloads a file from a public bucket. Does not require authentication.
      tags:
      - Objects
      security: []
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: File not found
  /object/sign/{bucketName}/{objectPath}:
    post:
      operationId: createSignedUrl
      summary: Create a signed URL
      description: Generates a time-limited signed URL for accessing a private file without authentication. Useful for sharing temporary access to files.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - expiresIn
              properties:
                expiresIn:
                  type: integer
                  description: Number of seconds until the URL expires
                  minimum: 1
      responses:
        '200':
          description: Signed URL created
          content:
            application/json:
              schema:
                type: object
                properties:
                  signedURL:
                    type: string
                    format: uri
                    description: The signed URL for file access
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /object/list/{bucketName}:
    post:
      operationId: listObjects
      summary: List objects in a bucket
      description: Returns a list of objects within a bucket, optionally filtered by prefix (folder path). Supports pagination with limit and offset.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/BucketName'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prefix:
                  type: string
                  description: Filter objects by path prefix (folder)
                  default: ''
                limit:
                  type: integer
                  description: Maximum number of objects to return
                  default: 100
                  minimum: 1
                offset:
                  type: integer
                  description: Number of objects to skip
                  default: 0
                  minimum: 0
                sortBy:
                  type: object
                  properties:
                    column:
                      type: string
                      description: Column to sort by
                      enum:
                      - name
                      - updated_at
                      - created_at
                      - last_accessed_at
                    order:
                      type: string
                      description: Sort direction
                      enum:
                      - asc
                      - desc
                search:
                  type: string
                  description: Search string to filter object names
      responses:
        '200':
          description: Successfully retrieved objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorageObject'
        '401':
          description: Unauthorized
        '404':
          description: Bucket not found
  /object/move:
    post:
      operationId: moveObject
      summary: Move a file
      description: Moves a file from one location to another within the same bucket or across buckets. Can also be used to rename files.
      tags:
      - Objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveObjectRequest'
      responses:
        '200':
          description: File moved successfully
        '401':
          description: Unauthorized
        '404':
          description: Source file not found
  /object/copy:
    post:
      operationId: copyObject
      summary: Copy a file
      description: Creates a copy of a file at a new location within the same bucket or across buckets.
      tags:
      - Objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyObjectRequest'
      responses:
        '200':
          description: File copied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                    description: Path of the copied file
        '401':
          description: Unauthorized
        '404':
          description: Source file not found
components:
  schemas:
    StorageObject:
      type: object
      properties:
        name:
          type: string
          description: Name of the object
        id:
          type: string
          format: uuid
          description: Unique identifier for the object
        bucket_id:
          type: string
          description: ID of the bucket containing the object
        owner:
          type: string
          format: uuid
          description: UUID of the object owner
        created_at:
          type: string
          format: date-time
          description: Timestamp when the object was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the object was last updated
        last_accessed_at:
          type: string
          format: date-time
          description: Timestamp when the object was last accessed
        metadata:
          type: object
          properties:
            size:
              type: integer
              description: File size in bytes
            mimetype:
              type: string
              description: MIME type of the file
            cacheControl:
              type: string
              description: Cache-Control header value
          description: File metadata
    CopyObjectRequest:
      type: object
      required:
      - bucketId
      - sourceKey
      - destinationKey
      properties:
        bucketId:
          type: string
          description: Source bucket ID
        sourceKey:
          type: string
          description: Path of the file to copy
        destinationBucket:
          type: string
          description: Destination bucket ID (defaults to source bucket)
        destinationKey:
          type: string
          description: Path for the copy
    ObjectResponse:
      type: object
      properties:
        Key:
          type: string
          description: Full path of the uploaded object
    MoveObjectRequest:
      type: object
      required:
      - bucketId
      - sourceKey
      - destinationKey
      properties:
        bucketId:
          type: string
          description: Source bucket ID
        sourceKey:
          type: string
          description: Current path of the file
        destinationBucket:
          type: string
          description: Destination bucket ID (defaults to source bucket)
        destinationKey:
          type: string
          description: New path for the file
  parameters:
    BucketName:
      name: bucketName
      in: path
      required: true
      description: Name of the storage bucket
      schema:
        type: string
    ObjectPath:
      name: objectPath
      in: path
      required: true
      description: Path to the object within the bucket, including folder hierarchy and filename.
      schema:
        type: string
  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