Convex Custom Domains API

openapi: 3.2.0
info:
  title: Convex Management Custom Domains API
  description: The Convex Management API is a REST API for provisioning and managing Convex projects, deployments, teams, and access credentials programmatically.
  version: v1
  contact:
    name: Convex Platform Support
    email: platforms@convex.dev
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
servers:
- url: https://api.convex.dev/v1
  description: Convex Management API Production Server
security:
- teamToken: []
- oauthTeamToken: []
tags:
- name: Custom Domains
  description: Configure custom domain names for Convex deployments. Supports both convexCloud (function API) and convexSite (HTTP actions) request destinations.
paths:
  /deployments/{deployment_name}/custom_domains/create:
    post:
      operationId: createCustomDomain
      summary: Create a custom domain
      description: 'Associates a custom domain with a Convex deployment. Supports two request destination types: convexCloud for routing to the function API (queries, mutations, actions), and convexSite for routing to HTTP action endpoints. Domain verification and DNS configuration is handled separately.'
      tags:
      - Custom Domains
      parameters:
      - $ref: '#/components/parameters/deploymentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomDomainRequest'
      responses:
        '200':
          description: Custom domain created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
        '400':
          description: Bad request — invalid domain or destination type
        '401':
          description: Unauthorized — missing or invalid token
  /deployments/{deployment_name}/custom_domains/list:
    get:
      operationId: listCustomDomains
      summary: List custom domains for a deployment
      description: Returns all custom domains configured for a deployment. Each entry includes the domain name, request destination type, and verification status.
      tags:
      - Custom Domains
      parameters:
      - $ref: '#/components/parameters/deploymentName'
      responses:
        '200':
          description: Custom domains listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomDomain'
        '401':
          description: Unauthorized — missing or invalid token
  /deployments/{deployment_name}/custom_domains/delete:
    post:
      operationId: deleteCustomDomain
      summary: Delete a custom domain
      description: Removes a custom domain association from a Convex deployment. After deletion, traffic to the domain will no longer be routed to the deployment. DNS records should be removed separately.
      tags:
      - Custom Domains
      parameters:
      - $ref: '#/components/parameters/deploymentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  description: The custom domain name to remove.
      responses:
        '200':
          description: Custom domain deleted successfully
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Custom domain not found
components:
  schemas:
    CustomDomain:
      type: object
      required:
      - domain
      - request_destination
      properties:
        domain:
          type: string
          description: The custom domain name (e.g. "api.example.com").
        request_destination:
          type: string
          description: The routing destination for requests to this domain. convexCloud routes to the function API; convexSite routes to HTTP action endpoints.
          enum:
          - convexCloud
          - convexSite
    CreateCustomDomainRequest:
      type: object
      required:
      - domain
      - request_destination
      properties:
        domain:
          type: string
          description: The custom domain name to associate with the deployment.
        request_destination:
          type: string
          description: The routing destination for requests to this domain.
          enum:
          - convexCloud
          - convexSite
  parameters:
    deploymentName:
      name: deployment_name
      in: path
      required: true
      description: The unique name of the deployment (e.g. "happy-otter-123"). This is the subdomain portion of the deployment URL at convex.cloud.
      schema:
        type: string
  securitySchemes:
    teamToken:
      type: http
      scheme: bearer
      description: Team Access Token created in the Convex dashboard team settings. Grants management access to all projects and deployments within the team.
    oauthTeamToken:
      type: http
      scheme: bearer
      description: OAuth Application Token issued by Convex for third-party integrations acting on behalf of a user's team. Obtained via the Convex OAuth flow.
    oauthProjectToken:
      type: http
      scheme: bearer
      description: OAuth Application Token scoped to a specific project, issued by Convex for third-party integrations.
externalDocs:
  description: Convex Management API Documentation
  url: https://docs.convex.dev/management-api