Convex CustomDomains 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. It enables developers and platform integrations to create projects, manage deployments across cloud regions, configure custom domains, and handle team membership without using the Convex dashboard. The API supports two token types: Team Access Tokens (for managing your own team''s resources) and OAuth Application Tokens (for third-party integrations acting on behalf of users). A JavaScript client wrapper is available via the @convex-dev/platform npm package. The API is currently in Beta.'
  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: CustomDomains
  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:
      - CustomDomains
      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:
      - CustomDomains
      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:
      - CustomDomains
      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:
    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
    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
  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