Supabase Projects API

openapi: 3.2.0
info:
  title: Supabase Management Projects 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: Projects
  description: Manage Supabase projects including creation, configuration, pausing, restoring, and deletion.
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
components:
  schemas:
    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
    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
    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
    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
  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
  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