openapi: 3.2.0
info:
  title: Supabase Management Database API
  description: The Supabase Management API provides programmatic access to manage Supabase projects and organizations. It supports operations for creating, updating, and deleting projects, managing database configurations, retrieving project API keys, controlling organization membership, deploying Edge Functions, managing secrets, configuring custom domains, and monitoring project health. Authentication is handled via personal access tokens or OAuth2 tokens.
  version: 1.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://api.supabase.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Database
  description: Manage database configurations, migrations, and extensions.
paths:
  /projects/{ref}/database/migrations:
    get:
      operationId: listDatabaseMigrations
      summary: List database migrations
      description: Returns a list of all migrations that have been applied to the project database, stored in the supabase_migrations schema.
      tags:
      - Database
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved migrations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatabaseMigration'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: createDatabaseMigration
      summary: Create a database migration
      description: Creates and runs a new SQL migration on the project database. The migration is recorded in the supabase_migrations schema.
      tags:
      - Database
      parameters:
      - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMigrationRequest'
      responses:
        '201':
          description: Migration created and applied successfully
        '400':
          description: Bad request - invalid SQL or migration error
        '401':
          description: Unauthorized
components:
  parameters:
    ProjectRef:
      name: ref
      in: path
      required: true
      description: The unique reference ID for the project, found in the project settings or URL.
      schema:
        type: string
  schemas:
    DatabaseMigration:
      type: object
      properties:
        version:
          type: string
          description: Migration version identifier
        name:
          type: string
          description: Migration name
        statements:
          type: array
          items:
            type: string
          description: SQL statements in the migration
    CreateMigrationRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: SQL statements to execute in the migration
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token or OAuth2 token for authentication. Generate tokens from the Supabase Dashboard under Account > Access Tokens.
externalDocs:
  description: Supabase Management API Documentation
  url: https://supabase.com/docs/reference/api/introduction