Convex Deployments API

openapi: 3.2.0
info:
  title: Convex Management Deployments 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: Deployments
  description: Create, list, retrieve, update, and delete Convex cloud and local deployments. Deployments are the runtime environments where Convex backend functions execute.
paths:
  /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
components:
  parameters:
    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
    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:
    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.
    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
  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