> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or replace env var

> Create or replace env var. If there is an existing env var with the same name as the one specified in the request, will replace the existing env var with the provided fields



## OpenAPI

````yaml /openapi.yaml put /v1/env_var
openapi: 3.1.1
info:
  version: 1.0.0
  title: Braintrust API
  description: >-
    API specification for the backend data server. The API is hosted globally at

    https://api.braintrust.dev or in your own environment.


    You can access the OpenAPI spec for this API at
    https://github.com/braintrustdata/braintrust-openapi.
  license:
    name: Apache 2.0
servers:
  - url: https://api.braintrust.dev
security:
  - bearerAuth: []
  - {}
paths:
  /v1/env_var:
    put:
      tags:
        - EnvVars
      summary: Create or replace env var
      description: >-
        Create or replace env var. If there is an existing env var with the same
        name as the one specified in the request, will replace the existing env
        var with the provided fields
      operationId: putEnvVar
      requestBody:
        description: Any desired information about the new env var object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                object_type:
                  type: string
                  enum:
                    - organization
                    - project
                    - function
                    - mcp_server
                  description: >-
                    The type of the object the environment variable is scoped
                    for
                object_id:
                  type: string
                  format: uuid
                  description: The id of the object the environment variable is scoped for
                name:
                  type: string
                  description: The name of the environment variable
                value:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The value of the environment variable. Will be encrypted at
                    rest.
                metadata:
                  type:
                    - object
                    - 'null'
                  additionalProperties: {}
                  description: >-
                    Optional metadata associated with the environment variable
                    when managed via the function secrets API
                secret_type:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Optional classification for the secret (for example, the AI
                    provider name)
              required:
                - object_type
                - object_id
                - name
      responses:
        '200':
          description: Returns the new env var object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVar'
        '400':
          description: >-
            The request was unacceptable, often due to missing a required
            parameter
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '401':
          description: No valid API key provided
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '403':
          description: The API key doesn’t have permissions to perform the request
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '429':
          description: >-
            Too many requests hit the API too quickly. We recommend an
            exponential backoff of your requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        '500':
          description: Something went wrong on Braintrust's end. (These are rare.)
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
      security:
        - bearerAuth: []
        - {}
components:
  schemas:
    EnvVar:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the environment variable
        object_type:
          type: string
          enum:
            - organization
            - project
            - function
            - mcp_server
          description: The type of the object the environment variable is scoped for
        object_id:
          type: string
          format: uuid
          description: The id of the object the environment variable is scoped for
        name:
          type: string
          description: The name of the environment variable
        created:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of environment variable creation
        secret_updated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date of last update to the encrypted secret value itself
        secret_updated_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
          description: User id of the last update to the encrypted secret value
        used:
          type:
            - string
            - 'null'
          format: date-time
          description: Date the environment variable was last used
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: {}
          description: >-
            Optional metadata associated with the environment variable when
            managed via the function secrets API
        preview_secret:
          type:
            - string
            - 'null'
          description: Redacted preview of the stored secret value
        secret_type:
          type:
            - string
            - 'null'
          description: >-
            Optional classification for the secret (for example, the AI provider
            name)
        secret_category:
          type: string
          enum:
            - env_var
            - ai_provider
            - sandbox_provider
            - automation_integration
          default: env_var
          description: >-
            The category of the secret: env_var for regular environment
            variables, ai_provider for AI provider API keys
      required:
        - id
        - object_type
        - object_id
        - name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or JWT
      description: >-
        Most Braintrust endpoints are authenticated by providing your API key as
        a header `Authorization: Bearer [api_key]` to your HTTP request. You can
        create an API key in the Braintrust [organization settings
        page](https://www.braintrustdata.com/app/settings?subroute=api-keys).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.