Braintrust EnvVars API
The EnvVars API from Braintrust — 2 operation(s) for envvars.
OpenAPI Specification
openapi: 3.1.1
info:
version: 1.0.0
title: Braintrust Acls EnvVars 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: []
- {}
tags:
- name: EnvVars
paths:
/v1/env_var:
post:
tags:
- EnvVars
security:
- bearerAuth: []
- {}
operationId: postEnvVar
description: Create a new env_var. If there is an existing env_var with the same name as the one specified in the request, will return the existing env_var unmodified
summary: Create env_var
requestBody:
description: Any desired information about the new env_var object
required: false
content:
application/json:
schema:
type: object
properties:
object_type:
type: string
enum:
- organization
- project
- function
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
nullable: true
description: The value of the environment variable. Will be encrypted at rest.
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: Optional metadata associated with the environment variable when managed via the function secrets API
secret_type:
type: string
nullable: true
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:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
put:
tags:
- EnvVars
security:
- bearerAuth: []
- {}
operationId: putEnvVar
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
summary: Create or replace env_var
requestBody:
description: Any desired information about the new env_var object
required: false
content:
application/json:
schema:
type: object
properties:
object_type:
type: string
enum:
- organization
- project
- function
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
nullable: true
description: The value of the environment variable. Will be encrypted at rest.
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: Optional metadata associated with the environment variable when managed via the function secrets API
secret_type:
type: string
nullable: true
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:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
get:
operationId: getEnvVar
tags:
- EnvVars
description: List out all env_vars. The env_vars are sorted by creation date, with the most recently-created env_vars coming first
summary: List env_vars
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AppLimitParam'
- $ref: '#/components/parameters/Ids'
- $ref: '#/components/parameters/EnvVarName'
- $ref: '#/components/parameters/EnvVarObjectType'
- $ref: '#/components/parameters/EnvVarObjectId'
responses:
'200':
description: Returns a list of env_var objects
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/EnvVar'
description: A list of env_var objects
required:
- objects
additionalProperties: false
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
/v1/env_var/{env_var_id}:
get:
operationId: getEnvVarId
tags:
- EnvVars
description: Get an env_var object by its id
summary: Get env_var
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/EnvVarIdParam'
responses:
'200':
description: Returns the 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:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
patch:
operationId: patchEnvVarId
tags:
- EnvVars
description: Partially update an env_var object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.
summary: Partially update env_var
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/EnvVarIdParam'
requestBody:
description: Fields to update
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the environment variable
value:
type: string
nullable: true
description: The value of the environment variable. Will be encrypted at rest.
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: Optional metadata associated with the environment variable when managed via the function secrets API
secret_type:
type: string
nullable: true
description: Optional classification for the secret (for example, the AI provider name)
required:
- name
responses:
'200':
description: Returns the 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:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
delete:
operationId: deleteEnvVarId
tags:
- EnvVars
description: Delete an env_var object by its id
summary: Delete env_var
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/EnvVarIdParam'
responses:
'200':
description: Returns the deleted 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:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'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:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
components:
schemas:
EnvVarObjectId:
type: string
format: uuid
description: The id of the object the environment variable is scoped for
EnvVarIdParam:
type: string
format: uuid
description: EnvVar id
AppLimitParam:
type: integer
nullable: true
minimum: 0
description: Limit the number of objects to return
EnvVarName:
type: string
description: Name of the env_var to search for
EnvVarObjectType:
type: string
enum:
- organization
- project
- function
description: The type of the object the environment variable is scoped for
EnvVar:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the environment variable
object_type:
type: string
enum:
- organization
- project
- function
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
nullable: true
format: date-time
description: Date of environment variable creation
secret_updated_at:
type: string
nullable: true
format: date-time
description: Date of last update to the encrypted secret value itself
secret_updated_by_user_id:
type: string
nullable: true
format: uuid
description: User id of the last update to the encrypted secret value
used:
type: string
nullable: true
format: date-time
description: Date the environment variable was last used
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: Optional metadata associated with the environment variable when managed via the function secrets API
preview_secret:
type: string
nullable: true
description: Redacted preview of the stored secret value
secret_type:
type: string
nullable: true
description: Optional classification for the secret (for example, the AI provider name)
secret_category:
type: string
enum:
- env_var
- ai_provider
- sandbox_provider
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
Ids:
anyOf:
- type: string
format: uuid
- type: array
items:
type: string
format: uuid
description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
parameters:
EnvVarName:
schema:
$ref: '#/components/schemas/EnvVarName'
required: false
description: Name of the env_var to search for
name: env_var_name
in: query
allowReserved: true
Ids:
schema:
$ref: '#/components/schemas/Ids'
required: false
description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
name: ids
in: query
AppLimitParam:
schema:
$ref: '#/components/schemas/AppLimitParam'
required: false
description: Limit the number of objects to return
name: limit
in: query
EnvVarIdParam:
schema:
$ref: '#/components/schemas/EnvVarIdParam'
required: true
description: EnvVar id
name: env_var_id
in: path
EnvVarObjectId:
schema:
$ref: '#/components/schemas/EnvVarObjectId'
required: false
description: The id of the object the environment variable is scoped for
name: object_id
in: query
EnvVarObjectType:
schema:
$ref: '#/components/schemas/EnvVarObjectType'
required: false
description: The type of the object the environment variable is scoped for
name: object_type
in: query
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).'