openapi: 3.2.0
info:
  title: Convex Deployment Platform Environment Variables API
  description: The Convex Deployment Platform API is a deployment-scoped administrative REST API for configuring individual Convex deployments.
  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: Environment Variables
  description: Manage environment variables for a Convex deployment. Environment variables are key-value pairs accessible to backend functions at runtime via process.env. Changes to environment variables take effect after the next deployment push.
paths:
  /list_environment_variables:
    post:
      operationId: listEnvironmentVariables
      summary: List environment variables
      description: Retrieves all environment variables configured for the deployment. Returns an array of key-value pairs representing the current environment variable configuration. Sensitive values are returned in full and should be handled securely. Authentication requires a deployment key, Team Access Token, or OAuth Application Token formatted as "Convex {token}" in the Authorization header.
      tags:
      - Environment Variables
      responses:
        '200':
          description: Environment variables retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnvironmentVariable'
        '401':
          description: 'Unauthorized — missing or invalid Authorization header. Ensure the token is prefixed with "Convex " (e.g. "Authorization: Convex <token>").'
        '403':
          description: Forbidden — the provided token does not have administrative access to this deployment.
  /update_environment_variables:
    post:
      operationId: updateEnvironmentVariables
      summary: Update environment variables
      description: Creates or updates one or more environment variables for the deployment. Existing variables with matching keys are overwritten. Variables not included in the request are left unchanged. Changes take effect after the next deployment push. Authentication requires a deployment key, Team Access Token, or OAuth Application Token formatted as "Convex {token}" in the Authorization header.
      tags:
      - Environment Variables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - changes
              properties:
                changes:
                  type: array
                  description: Array of environment variable key-value pairs to create or update.
                  items:
                    $ref: '#/components/schemas/EnvironmentVariable'
      responses:
        '200':
          description: Environment variables updated successfully
        '400':
          description: Bad request — invalid variable name or value format
        '401':
          description: Unauthorized — missing or invalid Authorization header. Ensure the token is prefixed with "Convex ".
        '403':
          description: Forbidden — the provided token does not have administrative access to this deployment.
  /delete_environment_variables:
    post:
      operationId: deleteEnvironmentVariables
      summary: Delete environment variables
      description: Removes one or more environment variables from the deployment by their key names. Deleted variables are no longer accessible to backend functions after the next deployment push. Authentication requires a deployment key, Team Access Token, or OAuth Application Token formatted as "Convex {token}" in the Authorization header.
      tags:
      - Environment Variables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - names
              properties:
                names:
                  type: array
                  description: Array of environment variable key names to delete.
                  items:
                    type: string
                    description: The key name of the environment variable to delete.
      responses:
        '200':
          description: Environment variables deleted successfully
        '400':
          description: Bad request — invalid variable name format
        '401':
          description: Unauthorized — missing or invalid Authorization header.
        '403':
          description: Forbidden — the provided token does not have administrative access to this deployment.
components:
  schemas:
    EnvironmentVariable:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The environment variable key name. Must follow standard environment variable naming conventions (uppercase letters, digits, underscores).
          pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          example: DATABASE_URL
        value:
          type: string
          description: The environment variable value. May contain any string value including connection strings, API keys, or configuration data.
          example: https://db.example.com/mydb
  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