openapi: 3.1.0
info:
  title: Convex Deployment Platform 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
externalDocs:
  description: Convex Deployment Platform API Documentation
  url: https://docs.convex.dev/deployment-platform-api
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.
tags:
  - name: EnvironmentVariables
    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.
security:
  - convexAuth: []
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:
        - EnvironmentVariables
      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:
        - EnvironmentVariables
      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:
        - EnvironmentVariables
      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:
  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.

  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'