Braintrust Functions API
The Functions API from Braintrust — 3 operation(s) for functions.
OpenAPI Specification
openapi: 3.1.1
info:
version: 1.0.0
title: Braintrust Acls Functions 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: Functions
paths:
/v1/function:
post:
tags:
- Functions
security:
- bearerAuth: []
- {}
operationId: postFunction
description: Create a new function. If there is an existing function in the project with the same slug as the one specified in the request, will return the existing function unmodified
summary: Create function
requestBody:
description: Any desired information about the new function object
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFunction'
responses:
'200':
description: Returns the new function object
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'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:
- Functions
security:
- bearerAuth: []
- {}
operationId: putFunction
description: Create or replace function. If there is an existing function in the project with the same slug as the one specified in the request, will replace the existing function with the provided fields
summary: Create or replace function
requestBody:
description: Any desired information about the new function object
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFunction'
responses:
'200':
description: Returns the new function object
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'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: getFunction
tags:
- Functions
description: List out all functions. The functions are sorted by creation date, with the most recently-created functions coming first
summary: List functions
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AppLimitParam'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- $ref: '#/components/parameters/Ids'
- $ref: '#/components/parameters/FunctionName'
- $ref: '#/components/parameters/ProjectName'
- $ref: '#/components/parameters/ProjectIdQuery'
- $ref: '#/components/parameters/Slug'
- $ref: '#/components/parameters/PromptVersion'
- $ref: '#/components/parameters/PromptEnvironment'
- $ref: '#/components/parameters/OrgName'
responses:
'200':
description: Returns a list of function objects
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Function'
description: A list of function 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/function/{function_id}:
get:
operationId: getFunctionId
tags:
- Functions
description: Get a function object by its id
summary: Get function
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/FunctionIdParam'
- $ref: '#/components/parameters/PromptVersion'
- $ref: '#/components/parameters/PromptEnvironment'
responses:
'200':
description: Returns the function object
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'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: patchFunctionId
tags:
- Functions
description: Partially update a function 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 function
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/FunctionIdParam'
requestBody:
description: Fields to update
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PatchFunction'
responses:
'200':
description: Returns the function object
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'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: deleteFunctionId
tags:
- Functions
description: Delete a function object by its id
summary: Delete function
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/FunctionIdParam'
responses:
'200':
description: Returns the deleted function object
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'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/function/{function_id}/invoke:
post:
operationId: postFunctionIdInvoke
tags:
- Functions
description: Invoke a function.
summary: Invoke function
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/FunctionIdParam'
requestBody:
description: Function invocation parameters
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeApi'
responses:
'200':
description: Function invocation response
content:
application/json:
schema:
nullable: true
components:
schemas:
ResponseFormatNullish:
anyOf:
- type: object
properties:
type:
type: string
enum:
- json_object
required:
- type
title: json_object
- type: object
properties:
type:
type: string
enum:
- json_schema
json_schema:
$ref: '#/components/schemas/ResponseFormatJsonSchema'
required:
- type
- json_schema
title: json_schema
- type: object
properties:
type:
type: string
enum:
- text
required:
- type
title: text
- type: 'null'
GraphNode:
anyOf:
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- function
function:
$ref: '#/components/schemas/FunctionIdRef'
required:
- type
- function
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- input
description: The input to the graph
required:
- type
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- output
description: The output of the graph
required:
- type
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- literal
value:
nullable: true
description: A literal value to be returned
required:
- type
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- btql
expr:
type: string
description: A BTQL expression to be evaluated
required:
- type
- expr
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- gate
condition:
type: string
nullable: true
description: A BTQL expression to be evaluated
required:
- type
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- aggregator
required:
- type
- type: object
properties:
description:
type: string
nullable: true
description: The description of the node
position:
type: object
nullable: true
properties:
x:
type: number
description: The x position of the node
y:
type: number
description: The y position of the node
required:
- x
- y
description: The position of the node
type:
type: string
enum:
- prompt_template
prompt:
$ref: '#/components/schemas/PromptBlockData'
required:
- type
- prompt
PromptOptionsNullish:
type: object
nullable: true
properties:
model:
type: string
params:
$ref: '#/components/schemas/ModelParams'
position:
type: string
OrgName:
type: string
description: Filter search results to within a particular organization
PromptVersion:
type: string
description: 'Retrieve prompt at a specific version.
The version id can either be a transaction id (e.g. ''1000192656880881099'') or a version identifier (e.g. ''81cd05ee665fdfb3'').'
ModelParams:
anyOf:
- type: object
properties:
use_cache:
type: boolean
reasoning_enabled:
type: boolean
reasoning_budget:
type: number
temperature:
type: number
top_p:
type: number
max_tokens:
type: number
max_completion_tokens:
type: number
description: The successor to max_tokens
frequency_penalty:
type: number
presence_penalty:
type: number
response_format:
$ref: '#/components/schemas/ResponseFormatNullish'
tool_choice:
anyOf:
- type: string
enum:
- auto
title: auto
- type: string
enum:
- none
title: none
- type: string
enum:
- required
title: required
- type: object
properties:
type:
type: string
enum:
- function
function:
type: object
properties:
name:
type: string
required:
- name
required:
- type
- function
title: function
function_call:
anyOf:
- type: string
enum:
- auto
title: auto
- type: string
enum:
- none
title: none
- type: object
properties:
name:
type: string
required:
- name
title: function
n:
type: number
stop:
type: array
items:
type: string
reasoning_effort:
type: string
enum:
- none
- minimal
- low
- medium
- high
verbosity:
type: string
enum:
- low
- medium
- high
additionalProperties:
nullable: true
title: OpenAIModelParams
x-stainless-skip:
- go
- type: object
properties:
use_cache:
type: boolean
reasoning_enabled:
type: boolean
reasoning_budget:
type: number
max_tokens:
type: number
temperature:
type: number
top_p:
type: number
top_k:
type: number
stop_sequences:
type: array
items:
type: string
max_tokens_to_sample:
type: number
description: This is a legacy parameter that should not be used.
required:
- max_tokens
- temperature
additionalProperties:
nullable: true
title: AnthropicModelParams
x-stainless-skip:
- go
- type: object
properties:
use_cache:
type: boolean
reasoning_enabled:
type: boolean
reasoning_budget:
type: number
temperature:
type: number
maxOutputTokens:
type: number
topP:
type: number
topK:
type: number
additionalProperties:
nullable: true
title: GoogleModelParams
x-stainless-skip:
- go
- type: object
properties:
use_cache:
type: boolean
reasoning_enabled:
type: boolean
reasoning_budget:
type: number
temperature:
type: number
topK:
type: number
additionalProperties:
nullable: true
title: WindowAIModelParams
x-stainless-skip:
- go
- type: object
properties:
use_cache:
type: boolean
reasoning_enabled:
type: boolean
reasoning_budget:
type: number
additionalProperties:
nullable: true
title: JsCompletionParams
x-stainless-skip:
- go
CreateFunction:
type: object
properties:
project_id:
type: string
format: uuid
description: Unique identifier for the project that the prompt belongs under
name:
type: string
minLength: 1
description: Name of the prompt
slug:
type: string
minLength: 1
description: Unique identifier for the prompt
description:
type: string
nullable: true
description: Textual description of the prompt
prompt_data:
$ref: '#/components/schemas/PromptDataNullish'
tags:
type: array
nullable: true
items:
type: string
description: A list of tags for the prompt
function_type:
$ref: '#/components/schemas/FunctionTypeEnumNullish'
function_data:
$ref: '#/components/schemas/FunctionData'
origin:
type: object
nullable: true
properties:
object_type:
$ref: '#/components/schemas/AclObjectType'
object_id:
type: string
format: uuid
description: Id of the object the function is originating from
internal:
type: boolean
nullable: true
description: The function exists for internal purposes and should not be displayed in the list of functions.
required:
- object_type
- object_id
function_schema:
type: object
nullable: true
properties:
parameters:
nullable: true
returns:
nullable: true
description: JSON schema for the function's parameters and return type
required:
- project_id
- name
- slug
- function_data
PromptBlockData:
anyOf:
- type: object
properties:
type:
type: string
enum:
- chat
messages:
type: array
items:
$ref: '#/components/schemas/ChatCompletionMessageParam'
tools:
type: string
required:
- type
- messages
title: chat
- type: object
properties:
type:
type: string
enum:
- completion
content:
type: string
required:
- type
- content
title: completion
PromptEnvironment:
type: string
description: 'Filter by environment slug. Cannot be used together with `version`.
For `GET /v1/prompt`, environment resolution currently requires the request to match a single prompt. If multiple prompts match, the endpoint returns `400` (for example when `limit=1` is not set). Use `limit=1` or other filters (for example `slug`, `project_id`) to narrow results.'
FunctionData:
anyOf:
- type: object
properties:
type:
type: string
enum:
- prompt
required:
- type
title: prompt
- type: object
properties:
type:
type: string
enum:
- code
data:
anyOf:
- allOf:
- type: object
properties:
type:
type: string
enum:
- bundle
required:
- type
- $ref: '#/components/schemas/CodeBundle'
title: bundle
- type: object
properties:
type:
type: string
enum:
- inline
runtime_context:
type: object
properties:
runtime:
type: string
enum:
- node
- python
- browser
- quickjs
version:
type: string
required:
- runtime
- version
code:
type: string
code_hash:
type: string
description: SHA256 hash of the code, computed at save time
required:
- type
- runtime_context
- code
title: inline
required:
- type
- data
title: code
- $ref: '#/components/schemas/GraphData'
- type: object
properties:
type:
type: string
enum:
- remote_eval
endpoint:
type: string
eval_name:
type: string
parameters:
type: object
additionalProperties:
nullable: true
parameters_version:
type: string
nullable: true
description: The version (transaction ID) of the parameters being used
required:
- type
- endpoint
- eval_name
- parameters
description: A remote eval to run
title: remote_eval
- type: object
properties:
type:
type: string
enum:
- global
name:
type: string
function_type:
$ref: '#/components/schemas/FunctionTypeEnum'
config:
type: object
nullable: true
additionalProperties:
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/braintrust/refs/heads/main/openapi/braintrust-functions-api-openapi.yml