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