openapi: 3.2.0
info:
  title: Supabase Storage Rendering 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: Rendering
  description: Serve and transform stored files including image resizing and format conversion.
paths:
  /render/image/authenticated/{bucketName}/{objectPath}:
    get:
      operationId: renderAuthenticatedImage
      summary: Render a transformed private image
      description: Downloads and optionally transforms a private image with resizing, format conversion, and quality adjustments applied on the fly.
      tags:
      - Rendering
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      - $ref: '#/components/parameters/Width'
      - $ref: '#/components/parameters/Height'
      - $ref: '#/components/parameters/Resize'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Quality'
      responses:
        '200':
          description: Transformed image content
          content:
            image/*:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: File not found
  /render/image/public/{bucketName}/{objectPath}:
    get:
      operationId: renderPublicImage
      summary: Render a transformed public image
      description: Downloads and optionally transforms a public image with resizing, format conversion, and quality adjustments applied on the fly.
      tags:
      - Rendering
      security: []
      parameters:
      - $ref: '#/components/parameters/BucketName'
      - $ref: '#/components/parameters/ObjectPath'
      - $ref: '#/components/parameters/Width'
      - $ref: '#/components/parameters/Height'
      - $ref: '#/components/parameters/Resize'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Quality'
      responses:
        '200':
          description: Transformed image content
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          description: File not found
components:
  parameters:
    Format:
      name: format
      in: query
      description: Output format for image transformation
      schema:
        type: string
        enum:
        - origin
        - avif
        - webp
    BucketName:
      name: bucketName
      in: path
      required: true
      description: Name of the storage bucket
      schema:
        type: string
    Height:
      name: height
      in: query
      description: Target height in pixels for image transformation
      schema:
        type: integer
        minimum: 1
    Quality:
      name: quality
      in: query
      description: Output quality for image transformation (1-100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
    ObjectPath:
      name: objectPath
      in: path
      required: true
      description: Path to the object within the bucket, including folder hierarchy and filename.
      schema:
        type: string
    Width:
      name: width
      in: query
      description: Target width in pixels for image transformation
      schema:
        type: integer
        minimum: 1
    Resize:
      name: resize
      in: query
      description: Resize mode for image transformation
      schema:
        type: string
        enum:
        - cover
        - contain
        - fill
  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