openapi: 3.1.0
info:
  title: Supabase Management 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
externalDocs:
  description: Supabase Management API Documentation
  url: https://supabase.com/docs/reference/api/introduction
servers:
  - url: https://api.supabase.com/v1
    description: Production Server
tags:
  - name: Database
    description: >-
      Manage database configurations, migrations, and extensions.
  - name: Domains
    description: >-
      Configure custom domains and vanity subdomains for projects.
  - name: Functions
    description: >-
      Deploy and manage Edge Functions for serverless compute at the edge.
  - name: Network
    description: >-
      Manage network restrictions, bans, and SSL enforcement.
  - name: Organizations
    description: >-
      Manage organizations including membership, billing, and settings.
  - name: Projects
    description: >-
      Manage Supabase projects including creation, configuration, pausing,
      restoring, and deletion.
  - name: Secrets
    description: >-
      Manage project secrets used by Edge Functions and other services.
security:
  - bearerAuth: []
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List all projects
      description: >-
        Returns a list of all projects belonging to the authenticated user
        across all organizations.
      tags:
        - Projects
      responses:
        '200':
          description: Successfully retrieved list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized - invalid or missing access token
    post:
      operationId: createProject
      summary: Create a new project
      description: >-
        Creates a new Supabase project within a specified organization. The
        project will be provisioned with a PostgreSQL database, Auth, Storage,
        and other services.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized
  /projects/{ref}:
    get:
      operationId: getProject
      summary: Get project details
      description: >-
        Retrieves detailed information about a specific project including its
        current status, region, database host, and configuration.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: >-
        Permanently deletes a Supabase project and all associated data including
        the database, storage files, and Edge Functions.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/api-keys:
    get:
      operationId: getProjectApiKeys
      summary: Get project API keys
      description: >-
        Retrieves the API keys (anon and service_role) for a specific project.
        These keys are used to authenticate requests to the project's APIs.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/health:
    get:
      operationId: getProjectHealth
      summary: Get project health status
      description: >-
        Returns the health status of all services in a project including the
        database, Auth, Storage, Realtime, and Edge Functions.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved health status
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceHealth'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/pause:
    post:
      operationId: pauseProject
      summary: Pause a project
      description: >-
        Pauses a Supabase project to stop incurring compute costs. The project
        database and services will become unavailable until restored.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project paused successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /projects/{ref}/restore:
    post:
      operationId: restoreProject
      summary: Restore a paused project
      description: >-
        Restores a previously paused project, making its database and services
        available again.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Project restored successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /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
  /projects/{ref}/functions:
    get:
      operationId: listFunctions
      summary: List Edge Functions
      description: >-
        Returns a list of all Edge Functions deployed to a project including
        their status, slug, and creation date.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved functions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EdgeFunction'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: createFunction
      summary: Create an Edge Function
      description: >-
        Deploys a new Edge Function to the project. The function will be
        globally distributed and accessible via HTTP requests.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunctionRequest'
      responses:
        '201':
          description: Function created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeFunction'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /projects/{ref}/functions/{function_slug}:
    get:
      operationId: getFunction
      summary: Get an Edge Function
      description: >-
        Retrieves details about a specific Edge Function including its slug,
        status, version, and creation date.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
        - $ref: '#/components/parameters/FunctionSlug'
      responses:
        '200':
          description: Successfully retrieved function
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeFunction'
        '401':
          description: Unauthorized
        '404':
          description: Function not found
    patch:
      operationId: updateFunction
      summary: Update an Edge Function
      description: >-
        Updates an existing Edge Function with new code or configuration
        changes.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
        - $ref: '#/components/parameters/FunctionSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFunctionRequest'
      responses:
        '200':
          description: Function updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeFunction'
        '401':
          description: Unauthorized
        '404':
          description: Function not found
    delete:
      operationId: deleteFunction
      summary: Delete an Edge Function
      description: >-
        Permanently removes an Edge Function from the project.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
        - $ref: '#/components/parameters/FunctionSlug'
      responses:
        '200':
          description: Function deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Function not found
  /projects/{ref}/secrets:
    get:
      operationId: listSecrets
      summary: List project secrets
      description: >-
        Returns a list of all encrypted secrets stored for a project. Secret
        values are not returned, only their names.
      tags:
        - Secrets
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved secrets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: createSecrets
      summary: Create project secrets
      description: >-
        Creates one or more encrypted secrets for the project. These secrets
        are available to Edge Functions as environment variables.
      tags:
        - Secrets
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '201':
          description: Secrets created successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteSecrets
      summary: Delete project secrets
      description: >-
        Deletes one or more secrets from the project by their names.
      tags:
        - Secrets
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Secrets deleted successfully
        '401':
          description: Unauthorized
  /projects/{ref}/custom-hostname:
    get:
      operationId: getCustomHostname
      summary: Get custom hostname configuration
      description: >-
        Retrieves the custom hostname configuration for a project including
        its current status and verification records.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved custom hostname configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomHostname'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
    post:
      operationId: activateCustomHostname
      summary: Activate custom hostname
      description: >-
        Activates a custom hostname for the project. The custom domain must
        have DNS records properly configured before activation.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateCustomHostnameRequest'
      responses:
        '201':
          description: Custom hostname activated
        '400':
          description: Bad request - DNS not configured
        '401':
          description: Unauthorized
    delete:
      operationId: removeCustomHostname
      summary: Remove custom hostname
      description: >-
        Removes the custom hostname configuration from a project, reverting
        to the default supabase.co subdomain.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Custom hostname removed
        '401':
          description: Unauthorized
  /projects/{ref}/vanity-subdomain:
    get:
      operationId: getVanitySubdomain
      summary: Get vanity subdomain
      description: >-
        Retrieves the vanity subdomain configuration for a project.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved vanity subdomain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VanitySubdomain'
        '401':
          description: Unauthorized
    post:
      operationId: activateVanitySubdomain
      summary: Activate vanity subdomain
      description: >-
        Activates a vanity subdomain on supabase.co for the project. Use of
        vanity subdomains and custom domains is mutually exclusive.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateVanitySubdomainRequest'
      responses:
        '201':
          description: Vanity subdomain activated
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: removeVanitySubdomain
      summary: Remove vanity subdomain
      description: >-
        Removes the vanity subdomain from a project.
      tags:
        - Domains
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Vanity subdomain removed
        '401':
          description: Unauthorized
  /projects/{ref}/network-bans:
    get:
      operationId: listNetworkBans
      summary: List network bans
      description: >-
        Returns a list of IP addresses that are currently banned from accessing
        the project due to abusive traffic patterns such as multiple failed
        authentication attempts.
      tags:
        - Network
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved network bans
          content:
            application/json:
              schema:
                type: object
                properties:
                  banned_ipv4_addresses:
                    type: array
                    items:
                      type: string
                      format: ipv4
                    description: List of banned IPv4 addresses
        '401':
          description: Unauthorized
    delete:
      operationId: removeNetworkBans
      summary: Remove network bans
      description: >-
        Removes specified IP addresses from the project's network ban list,
        allowing them to access the project again.
      tags:
        - Network
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ipv4_addresses:
                  type: array
                  items:
                    type: string
                    format: ipv4
      responses:
        '200':
          description: Network bans removed
        '401':
          description: Unauthorized
  /projects/{ref}/network-restrictions:
    get:
      operationId: getNetworkRestrictions
      summary: Get network restrictions
      description: >-
        Retrieves the network restriction configuration for a project, which
        controls which IP addresses or CIDR ranges are allowed to connect to
        the database.
      tags:
        - Network
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      responses:
        '200':
          description: Successfully retrieved network restrictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRestrictions'
        '401':
          description: Unauthorized
    post:
      operationId: updateNetworkRestrictions
      summary: Update network restrictions
      description: >-
        Updates the allowed IP addresses or CIDR ranges that can connect to
        the project database.
      tags:
        - Network
      parameters:
        - $ref: '#/components/parameters/ProjectRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkRestrictions'
      responses:
        '200':
          description: Network restrictions updated
        '400':
          description: Bad request - invalid CIDR
        '401':
          description: Unauthorized
  /organizations:
    get:
      operationId: listOrganizations
      summary: List all organizations
      description: >-
        Returns a list of all organizations the authenticated user belongs to.
      tags:
        - Organizations
      responses:
        '200':
          description: Successfully retrieved organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
    post:
      operationId: createOrganization
      summary: Create an organization
      description: >-
        Creates a new organization that can contain Supabase projects and
        team members.
      tags:
        - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequest'
      responses:
        '201':
          description: Organization created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /organizations/{slug}/members:
    get:
      operationId: listOrganizationMembers
      summary: List organization members
      description: >-
        Returns a list of all members in an organization along with their
        roles and permissions.
      tags:
        - Organizations
      parameters:
        - $ref: '#/components/parameters/OrganizationSlug'
      responses:
        '200':
          description: Successfully retrieved members
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationMember'
        '401':
          description: Unauthorized
        '404':
          description: Organization not found
components:
  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.
  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
    FunctionSlug:
      name: function_slug
      in: path
      required: true
      description: >-
        The URL-friendly slug identifier for the Edge Function.
      schema:
        type: string
    OrganizationSlug:
      name: slug
      in: path
      required: true
      description: >-
        The URL-friendly slug identifier for the organization.
      schema:
        type: string
  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the project
        organization_id:
          type: string
          format: uuid
          description: ID of the organization that owns the project
        name:
          type: string
          description: Display name of the project
        region:
          type: string
          description: Cloud region where the project is hosted
          enum:
            - us-east-1
            - us-west-1
            - eu-west-1
            - eu-west-2
            - eu-central-1
            - ap-southeast-1
            - ap-southeast-2
            - ap-northeast-1
            - ap-south-1
            - sa-east-1
        created_at:
          type: string
          format: date-time
          description: Timestamp when the project was created
        database:
          $ref: '#/components/schemas/DatabaseConfig'
        status:
          type: string
          description: Current operational status of the project
          enum:
            - ACTIVE_HEALTHY
            - ACTIVE_UNHEALTHY
            - INACTIVE
            - INIT_FAILED
            - REMOVED
            - RESTORING
            - UPGRADING
            - PAUSING
            - COMING_UP
    CreateProjectRequest:
      type: object
      required:
        - name
        - organization_id
        - plan
        - region
        - db_pass
      properties:
        name:
          type: string
          description: Display name for the new project
        organization_id:
          type: string
          description: ID of the organization to create the project in
        plan:
          type: string
          description: Billing plan for the project
          enum:
            - free
            - pro
            - team
            - enterprise
        region:
          type: string
          description: Cloud region for the project
        db_pass:
          type: string
          description: Password for the project database
          minLength: 6
    DatabaseConfig:
      type: object
      properties:
        host:
          type: string
          description: Database host address
        version:
          type: string
          description: PostgreSQL version
    ApiKey:
      type: object
      properties:
        name:
          type: string
          description: Key name (anon or service_role)
          enum:
            - anon
            - service_role
        api_key:
          type: string
          description: The API key value
    ServiceHealth:
      type: object
      properties:
        name:
          type: string
          description: Name of the service
          enum:
            - database
            - auth
            - storage
            - realtime
            - functions
        healthy:
          type: boolean
          description: Whether the service is healthy
        status:
          type: string
          description: Detailed status message
    EdgeFunction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the function
        slug:
          type: string
          description: URL-friendly slug for the function
        name:
          type: string
          description: Display name of the function
        status:
          type: string
          description: Deployment status
          enum:
            - ACTIVE
            - REMOVED
            - THROTTLED
        version:
          type: integer
          description: Current deployment version
        created_at:
          type: string
          format: date-time
          description: Timestamp when the function was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the function was last updated
        verify_jwt:
          type: boolean
          description: Whether JWT verification is required for invocations
    CreateFunctionRequest:
      type: object
      required:
        - slug
        - name
        - body
      properties:
        slug:
          type: string
          description: URL-friendly slug for the function
        name:
          type: string
          description: Display name
        body:
          type: string
          description: Function source code
        verify_jwt:
          type: boolean
          description: Whether to require JWT verification
          default: true
    UpdateFunctionRequest:
      type: object
      properties:
        body:
          type: string
          description: Updated function source code
        verify_jwt:
          type: boolean
          description: Whether to require JWT verification
    Secret:
      type: object
      properties:
        name:
          type: string
          description: Name of the secret
    CreateSecretRequest:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Name for the secret
        value:
          type: string
          description: Secret value
    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
    CustomHostname:
      type: object
      properties:
        custom_hostname:
          type: string
          description: The custom hostname configured for the project
        status:
          type: string
          description: Verification status of the custom hostname
          enum:
            - active
            - pending
            - not_started
    ActivateCustomHostnameRequest:
      type: object
      required:
        - custom_hostname
      properties:
        custom_hostname:
          type: string
          description: The custom hostname to activate
    VanitySubdomain:
      type: object
      properties:
        custom_subdomain:
          type: string
          description: The vanity subdomain on supabase.co
        status:
          type: string
          description: Status of the vanity subdomain
          enum:
            - active
            - not_used
    ActivateVanitySubdomainRequest:
      type: object
      required:
        - vanity_subdomain
      properties:
        vanity_subdomain:
          type: string
          description: Desired vanity subdomain
    NetworkRestrictions:
      type: object
      properties:
        dbAllowedCidrs:
          type: array
          items:
            type: string
          description: List of CIDR ranges allowed to connect to the database
    Organization:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the organization
        name:
          type: string
          description: Display name of the organization
        slug:
          type: string
          description: URL-friendly slug
        billing_email:
          type: string
          format: email
          description: Billing contact email
        created_at:
          type: string
          format: date-time
          description: Timestamp when the organization was created
    CreateOrganizationRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name for the organization
    OrganizationMember:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: User identifier
        role_name:
          type: string
          description: Role assigned to the member
          enum:
            - Owner
            - Administrator
            - Developer
            - Read only
        primary_email:
          type: string
          format: email
          description: Email address of the member
        username:
          type: string
          description: Display name of the member