Convex Deployments API
Create, list, retrieve, update, and delete Convex cloud and local deployments. Deployments are the runtime environments where Convex backend functions execute.
OpenAPI Specification
openapi: 3.1.0
info:
title: Convex Deployment Platform AccessTokens Deployments API
description: The Convex Deployment Platform API is a deployment-scoped administrative REST API for configuring individual Convex deployments. It exposes private endpoints accessible only to deployment administrators and supports operations such as managing environment variables and other deployment configuration settings. Each deployment has its own endpoint in the format https://{deployment-name}.convex.cloud/api/v1/. Authentication requires an Authorization header using deployment keys, Team Access Tokens, or OAuth Application Tokens formatted as "Convex {token}". This API is currently in Beta and is intended for platform integrations and infrastructure automation workflows.
version: v1-beta
contact:
name: Convex Platform Support
email: platforms@convex.dev
url: https://www.convex.dev/community
termsOfService: https://www.convex.dev/terms
servers:
- url: https://{deploymentName}.convex.cloud/api/v1
description: Convex Deployment Server
variables:
deploymentName:
default: happy-otter-123
description: The deployment name found in the Convex dashboard or via the Management API. Each deployment has a unique subdomain under convex.cloud.
security:
- convexAuth: []
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:
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
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
schemas:
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
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.
securitySchemes:
convexAuth:
type: apiKey
in: header
name: Authorization
description: 'Authorization header using a deployment key, Team Access Token, or OAuth Application Token. The token must be prefixed with the string "Convex " (e.g. "Authorization: Convex prod:abc123..."). Deployment keys are created in the dashboard or via the Management API.'
externalDocs:
description: Convex Deployment Platform API Documentation
url: https://docs.convex.dev/deployment-platform-api