Supabase Domains API

openapi: 3.2.0
info:
  title: Supabase Management Domains 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: Domains
  description: Configure custom domains and vanity subdomains for projects.
paths:
  /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
components:
  schemas:
    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
    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
    ActivateCustomHostnameRequest:
      type: object
      required:
      - custom_hostname
      properties:
        custom_hostname:
          type: string
          description: The custom hostname to activate
    ActivateVanitySubdomainRequest:
      type: object
      required:
      - vanity_subdomain
      properties:
        vanity_subdomain:
          type: string
          description: Desired vanity subdomain
  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