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