Convex DeployKeys API

openapi: 3.2.0
info:
  title: Convex Management Deploy Keys 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: 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.
paths:
  /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
components:
  schemas:
    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.
    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.
  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
  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