Convex Management API

openapi: 3.1.0
info:
  title: Convex Management 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: [email protected]
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
externalDocs:
  description: Convex Management API Documentation
  url: https://docs.convex.dev/management-api
servers:
  - url: https://api.convex.dev/v1
    description: Convex Management API Production Server
tags:
  - name: AccessTokens
    description: >-
      Create and manage Team Access Tokens used for authenticating Management
      API requests on behalf of a team.
  - name: CustomDomains
    description: >-
      Configure custom domain names for Convex deployments. Supports both
      convexCloud (function API) and convexSite (HTTP actions) request
      destinations.
  - name: DeployKeys
    description: >-
      Create and manage deploy keys for CLI operations and CI/CD pipelines.
      Deploy keys authenticate the Convex CLI when pushing function code
      to a deployment.
  - name: Deployments
    description: >-
      Create, list, retrieve, update, and delete Convex cloud and local
      deployments. Deployments are the runtime environments where Convex
      backend functions execute.
  - name: Projects
    description: >-
      Create, list, retrieve, and delete Convex projects within a team.
      Projects group deployments and serve as the top-level organizational
      unit for Convex applications.
  - name: Teams
    description: >-
      Manage Convex teams, team members, and team-level access tokens.
      Teams are the billing and administrative unit that owns projects.
security:
  - teamToken: []
  - oauthTeamToken: []
paths:
  /teams/{team_id}/create_project:
    post:
      operationId: createProject
      summary: Create a new project
      description: >-
        Provisions a new Convex project within the specified team. Optionally
        creates an initial production deployment in the specified cloud region
        and deployment class. Returns the new project's ID and slug along with
        details of any provisioned deployment.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Bad request — invalid parameters
        '401':
          description: Unauthorized — missing or invalid token

  /teams/{team_id}/list_projects:
    get:
      operationId: listProjects
      summary: List projects in a team
      description: >-
        Returns all Convex projects belonging to the specified team. Each
        project entry includes its ID, slug, name, and associated deployment
        information. Useful for enumerating resources available to the
        authenticated token holder.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Projects listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token

  /projects/{project_id}:
    get:
      operationId: getProject
      summary: Get a project by ID
      description: >-
        Retrieves details for a specific Convex project identified by its
        integer project ID. Returns the project's name, slug, team association,
        and deployment summary.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found

  /teams/{team_id_or_slug}/projects/{project_slug}:
    get:
      operationId: getProjectBySlug
      summary: Get a project by team and project slug
      description: >-
        Retrieves a project by its human-readable slug within a team identified
        by either team ID or team slug. This is useful when project identifiers
        are stored as slugs rather than integer IDs.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/teamIdOrSlug'
        - $ref: '#/components/parameters/projectSlug'
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found

  /projects/{project_id}/delete:
    post:
      operationId: deleteProject
      summary: Delete a project
      description: >-
        Permanently deletes a Convex project and all associated deployments.
        This operation is irreversible. All deployments within the project are
        also deleted, and all associated resources (functions, data, files) are
        permanently removed.
      tags:
        - Projects
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Project deleted successfully
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Project not found

  /projects/{project_id}/deployments/create_cloud:
    post:
      operationId: createCloudDeployment
      summary: Create a cloud deployment
      description: >-
        Creates a new cloud deployment within a project in the specified region
        and deployment class. Cloud deployments run on Convex-managed
        infrastructure and are accessible via a public URL. Supports dev, prod,
        preview, and custom deployment types.
      tags:
        - Deployments
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCloudDeploymentRequest'
      responses:
        '200':
          description: Deployment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          description: Bad request — invalid region or deployment class
        '401':
          description: Unauthorized — missing or invalid token

  /projects/{project_id}/deployments/list:
    get:
      operationId: listDeployments
      summary: List deployments in a project
      description: >-
        Returns all deployments associated with a Convex project. Each
        deployment entry includes its ID, name, deployment URL, type (dev,
        prod, preview, custom), status, region, and class.
      tags:
        - Deployments
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Deployments listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized — missing or invalid token

  /deployments/{deployment_name}:
    get:
      operationId: getDeployment
      summary: Get a deployment by name
      description: >-
        Retrieves details for a specific deployment identified by its name
        (e.g. "happy-otter-123"). Returns the deployment URL, type, status,
        region, class, and associated project information.
      tags:
        - Deployments
      parameters:
        - $ref: '#/components/parameters/deploymentName'
      responses:
        '200':
          description: Deployment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Deployment not found

  /deployments/{deployment_name}/delete:
    post:
      operationId: deleteDeployment
      summary: Delete a deployment
      description: >-
        Permanently deletes a Convex deployment. All deployed functions,
        database data, and file storage associated with the deployment are
        permanently removed. This operation is irreversible.
      tags:
        - Deployments
      parameters:
        - $ref: '#/components/parameters/deploymentName'
      responses:
        '200':
          description: Deployment deleted successfully
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: Deployment not found

  /projects/{project_id}/deployment/default_prod:
    get:
      operationId: getDefaultProdDeployment
      summary: Get default production deployment
      description: >-
        Retrieves the default production deployment for a project. Most
        projects have a single production deployment designated as the default.
        Returns full deployment details including URL, region, class, and status.
      tags:
        - Deployments
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Default production deployment retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized — missing or invalid token
        '404':
          description: No default production deployment found

  /projects/{project_id}/deployments/create_deploy_key:
    post:
      operationId: createDeployKey
      summary: Create a deploy key
      description: >-
        Creates a new deploy key for a project, scoped to a specific deployment.
        Deploy keys are used by the Convex CLI and CI/CD pipelines to push
        function code to deployments. Keys can be standard or preview keys
        for Vercel-style preview deployments.
      tags:
        - DeployKeys
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeployKeyRequest'
      responses:
        '200':
          description: Deploy key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployKey'
        '401':
          description: Unauthorized — missing or invalid token

  /projects/{project_id}/deployment/deploy_key/list:
    get:
      operationId: listDeployKeys
      summary: List deploy keys for a project
      description: >-
        Returns all deploy keys associated with a Convex project. Includes
        key names, creation dates, and the deployment each key is scoped to.
        Key values are not returned after initial creation.
      tags:
        - DeployKeys
      parameters:
        - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: Deploy keys listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeployKey'
        '401':
          description: Unauthorized — missing or invalid token

  /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

  /teams/{team_id}/members:
    get:
      operationId: listTeamMembers
      summary: List team members
      description: >-
        Returns all members of the specified team along with their roles.
        Roles include admin (full management access) and developer (standard
        access). Useful for auditing team membership and access levels.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/teamId'
      responses:
        '200':
          description: Team members listed successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamMember'
        '401':
          description: Unauthorized — missing or invalid token

  /teams/{team_id}/create_access_token:
    post:
      operationId: createAccessToken
      summary: Create a team access token
      description: >-
        Creates a new Team Access Token for the specified team. Team Access
        Tokens are used to authenticate Management API requests and grant
        access to all projects and deployments within the team. The token
        value is only returned at creation time and should be stored securely.
      tags:
        - AccessTokens
      parameters:
        - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessTokenRequest'
      responses:
        '200':
          description: Access token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '401':
          description: Unauthorized — missing or invalid token

components:
  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.

  parameters:
    teamId:
      name: team_id
      in: path
      required: true
      description: >-
        The integer identifier of the Convex team. Available in the Convex
        dashboard when creating Team Access Tokens.
      schema:
        type: integer
        format: int64

    teamIdOrSlug:
      name: team_id_or_slug
      in: path
      required: true
      description: >-
        Either the integer team ID or the human-readable team slug.
      schema:
        type: string

    projectId:
      name: project_id
      in: path
      required: true
      description: >-
        The integer identifier of the Convex project. Obtainable via the
        List Projects endpoint or assigned during project creation.
      schema:
        type: integer
        format: int64

    projectSlug:
      name: project_slug
      in: path
      required: true
      description: >-
        The human-readable slug of the project within the team.
      schema:
        type: string

    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

  schemas:
    Project:
      type: object
      required:
        - id
        - slug
        - name
        - team_id
      properties:
        id:
          type: integer
          format: int64
          description: Unique integer identifier for the project.
        slug:
          type: string
          description: Human-readable URL-safe identifier for the project within the team.
        name:
          type: string
          description: Display name of the project.
        team_id:
          type: integer
          format: int64
          description: ID of the team that owns this project.

    Deployment:
      type: object
      required:
        - id
        - name
        - deployment_type
      properties:
        id:
          type: integer
          format: int64
          description: Unique integer identifier for the deployment.
        name:
          type: string
          description: >-
            Unique name of the deployment used as the subdomain of the
            deployment URL (e.g. "happy-otter-123").
        deployment_type:
          type: string
          description: The type of deployment environment.
          enum:
            - dev
            - prod
            - preview
            - custom
        deployment_class:
          type: string
          description: >-
            The compute class of the deployment, determining resource limits
            and pricing tier.
          enum:
            - s16
            - s256
            - d1024
        region:
          type: string
          description: The cloud region where the deployment runs.
          enum:
            - aws-us-east-1
            - aws-eu-west-1
        project_id:
          type: integer
          format: int64
          description: ID of the project that owns this deployment.
        url:
          type: string
          format: uri
          description: >-
            The base URL of the deployment in the format
            https://{name}.convex.cloud.

    CreateProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name for the new project.
        team_id:
          type: integer
          format: int64
          description: ID of the team to create the project in.
        deployment_region:
          type: string
          description: >-
            Cloud region for the initial production deployment.
            If omitted, no initial deployment is created.
          enum:
            - aws-us-east-1
            - aws-eu-west-1
        deployment_class:
          type: string
          description: Compute class for the initial production deployment.
          enum:
            - s16
            - s256
            - d1024

    CreateCloudDeploymentRequest:
      type: object
      required:
        - deployment_type
        - region
      properties:
        deployment_type:
          type: string
          description: The type of deployment environment to create.
          enum:
            - dev
            - prod
            - preview
            - custom
        region:
          type: string
          description: The cloud region where the deployment should run.
          enum:
            - aws-us-east-1
            - aws-eu-west-1
        deployment_class:
          type: string
          description: Compute class for the deployment.
          enum:
            - s16
            - s256
            - d1024

    CreateDeployKeyRequest:
      type: object
      required:
        - deployment_name
      properties:
        deployment_name:
          type: string
          description: The name of the deployment this key should be scoped to.
        key_name:
          type: string
          description: Optional human-readable name for the deploy key.

    DeployKey:
      type: object
      required:
        - name
        - deployment_name
      properties:
        name:
          type: string
          description: Human-readable name of the deploy key.
        deployment_name:
          type: string
          description: The deployment this key is scoped to.
        key:
          type: string
          description: >-
            The deploy key value. Only present immediately after creation;
            not returned by list operations.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the key was created.

    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

    TeamMember:
      type: object
      required:
        - id
        - role
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the team member.
        email:
          type: string
          format: email
          description: Email address of the team member.
        role:
          type: string
          description: The member's role within the team.
          enum:
            - admin
            - developer

    CreateAccessTokenRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Human-readable name for the access token.

    AccessToken:
      type: object
      required:
        - name
        - token
      properties:
        name:
          type: string
          description: Human-readable name of the access token.
        token:
          type: string
          description: >-
            The token value used for API authentication. Only returned at
            creation time; store it securely as it cannot be retrieved later.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the token was created.